Getting Started

Microsoft Dynamics NAV Documentation
Getting Started
See Also

To get started developing in Microsoft Dynamics NAV 2009, see the following.

To | See
Learn about the new features and scenarios in Microsoft Dynamics NAV 2009. | What's New in Developing for Microsoft Dynamics NAV 2009
Learn about the new features and scenarios in Microsoft Dynamics NAV 2009 SP1. | What's New in Developing for Microsoft Dynamics NAV 2009 SP1 What's New in Application Features for Microsoft Dynamics NAV 2009 SP1
Find information about developer or IT pro tasks. | Microsoft Dynamics NAV 2009 Documentation Roadmap
Learn about the RoleTailored client from the perspective of a developer. | Tour of the RoleTailored Client for Developers
Plan your solution. | Development Considerations
Develop objects in Microsoft Dynamics NAV. | Developing Objects
Transform forms to pages. | Transforming Forms to Pages
Add Web services functionality to Microsoft Dynamics NAV. | Working with Web Services
Learn more about working in the development environment. | Development Considerations
Read about performance considerations. | Improving Application Performance
Read about application security. | Creating a More Secure Application

Documentation Changes in Microsoft Dynamics NAV 2009

For Microsoft Dynamics NAV 2009, all developer and IT pro documentation has been moved to an online Help format to enable Web-based publishing in the MSDN Library. Here is a quick guide to where you can find the different Help content.

To | See
Find documentation about how to develop in Microsoft Dynamics NAV 2009. This includes all content previously provided in the Application Designer's Guide (w1w1adg.pdf). | Download the latest version of cside.chm from the Microsoft Download Center. Or view the latest online content in the MSDN Library.
Find documentation about how to install, configure, and deploy Microsoft Dynamics NAV 2009. | Download the latest version of nav_install.chm from the Microsoft Download Center. Or view the latest online content in the MSDN Library.
Find the Security Hardening Guide. | Download the latest version of the Security Hardening Guide in PDF format from the Microsoft Download Center.
Find what is new in the latest Help content. | What's New in Microsoft Dynamics NAV 2009 Developer and IT Pro Help.

See Also

Concepts

What's New in Developing for Microsoft Dynamics NAV 2009
Microsoft Dynamics NAV 2009 Documentation Roadmap

Other Resources

Tour of the RoleTailored Client for Developers

© 2010 Microsoft Corporation. All rights reserved.


What's New in Developing for Microsoft Dynamics NAV 2009

What's New in Developing for Microsoft Dynamics NAV 2009

This topic contains information about some of the new features and enhancements in Microsoft Dynamics NAV 2009.

What's new | See
Three-Tier Architecture With Microsoft Dynamics NAV 2009, the architecture has changed from a two- to three-tier architecture, enabling the new RoleTailored client and Web services. | RoleTailored Architecture in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.
Customizable, Role-Based User Interface Microsoft Dynamics NAV 2009 provides a more intuitive and customizable user interface (UI) called the RoleTailored client, which you can modify to support the job functions of different work roles in your organization. For each role that you support, you can create a customizable Role Center that displays key information that is required by that role and makes day-to-day tasks easier to complete. Partners, administrators, and super users can customize the UI for specific roles, and individual users can also further personalize the UI to meet their specific needs. | Tour of the RoleTailored Client for Developers Profiles and Role Centers in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.
Page Objects Microsoft Dynamics NAV 2009 includes a new object called a page, which is used in the same way as a form. However, unlike forms, you have the flexibility to display pages in the RoleTailored client or to publish a page using a Web service. You can also transform your existing form objects to page objects. | Creating and Maintaining Pages Transforming Forms to Pages
Improved Report Design and Functionality Microsoft Dynamics NAV 2009 offers an improved reporting experience. You can now create interactive reports to which you can add charts, graphs, tables, and other data presentation elements that were not available in previous versions of Microsoft Dynamics NAV. You can also save your reports in .pdf or .xls file formats. | Designing Reports for the RoleTailored Client Redesigning Classic Reports with Visual Studio Report Designer
Business Connections with Web Services Web services are a standard, widely used method for integrating applications and are supported in Microsoft Dynamics NAV 2009. By implementing Web services, you can access Microsoft Dynamics NAV data and business logic from outside the product in a standard, secure way. This enables you to connect Microsoft Dynamics NAV to other systems within an organization. | Working with Web Services
C/AL Data Types, Functions, Properties, and Triggers In Microsoft Dynamics NAV 2009, there are some changes to C/AL behavior and some changes to the data types, functions, properties, and triggers that are supported. To develop solutions for Microsoft Dynamics NAV 2009, you should be familiar with these changes. | Changes in C/AL Behavior and Support from Previous Versions of Microsoft Dynamics NAV

See Also

Concepts

Getting Started


What's New in Developing for Microsoft Dynamics NAV 2009 SP1

What's New in Developing for Microsoft Dynamics NAV 2009 SP1

This topic contains information about some of the new features and enhancements for developers and IT professionals in Microsoft Dynamics NAV 2009 SP1.

Note Note

If this version is your first experience with Microsoft Dynamics NAV 2009, then see What's New in Developing for Microsoft Dynamics NAV 2009 to read about features that were introduced in the original Microsoft Dynamics NAV 2009 release.

Note Tip

You can search for the string "only applies to Microsoft Dynamics NAV 2009 SP1" in cside.chm or in the MSDN Library to see a list of topics that were created to describe new functionality in Microsoft Dynamics NAV 2009 SP1.

What's new | See
RoleTailored client control add-ins RoleTailored client control add-ins extend the RoleTailored client with custom functionality. A control add-in is a visual element for displaying and modifying data on RoleTailored client pages. | Extending the RoleTailored Client Using Control Add-ins in Microsoft Dynamics 2009 SP1
Page Designer Page design enhancements include a new page wizard, categories for promoted actions, the ability to run pages with a Run button, and additions to the action image library. | Creating and Maintaining Pages
Report Designer You can now link from a report to a report. Other improvements include paging, an About This Report feature, matrix reports, and a progress indicator that gives you information while a report is being created. | Walkthrough: Creating a Link from a Report to a Report What is new in Dynamics NAV 2009 SP1 for Reporting
Form transformation control IDs and page translations The form transformation tool now provides more options for assigning IDs to page controls. You can also export translation strings from an application to a file and then add any translated strings from the translation file to the CaptionML properties of page controls. | Transforming Control and Menu IDs How to: Create the PageTranslations.txt File
Connect The RoleTailored client now includes a control add-in that that you can use on Role Centers to display role-based content from Microsoft Dynamics Online Connect, which is a Web service that distributes Microsoft Dynamics product and business information from sources such as CustomerSource and the Microsoft Dynamics community. | Including Microsoft Dynamics Online Connect on Role Centers
Application testing features New features help you test the business logic in your application. Among these features are test codeunits, test runner codeunits, UI handlers, and the ASSERTERROR keyword. | Testing the Application
Web services improvements Enhancements to Web services functionality include the implementation of a standard encoding algorithm to represent special characters in company names and support for products that use the Simple and Protected GSSAPI Negotiation Mechanism to initiate a Web services connection. | Web Services Changes for Microsoft Dynamics NAV 2009 SP1
Field text styling You can emphasize text in a field by changing its color and style. | How to: Style Field Text on a Page
Error List window After you compile an object, you can view errors or warnings about obsolete constructs in a three-tier environment by viewing the new Error List window. | Compiling Objects
Computers running the RoleTailored client in multiple time zones Microsoft Dynamics NAV Server can now interact with computers running the RoleTailored client in different time zones. Microsoft Dynamics NAV Server always presents data to clients in local time, and manages changes and local variations in Daylight Saving Time automatically. | Communicating with RoleTailored Clients in Different Time Zones
Changes in SQL Server usage In Microsoft Dynamics NAV 2009 SP1, creating a new user in Microsoft Dynamics NAV automatically creates corresponding SQL Server users in both the Microsoft Dynamics NAV database and the master database. Formerly, users were created only in the Microsoft Dynamics NAV database. This change requires Microsoft Dynamics NAV administrators to have greater permissions on SQL Server than for previous versions. Also, administrators are no longer required to set trace-flag 4616 on SQL Server. | Setting Database Owner and Security Administration Permissions
Best Practices Analyzer for Microsoft Dynamics NAV 2009 If you cannot get your three-tier implementation of Microsoft Dynamics NAV SP1 working even after completing Walkthrough: Installing the Three Tiers on Three Computers, then consider downloading and running the Best Practices Analyzer for Microsoft Dynamics NAV 2009. Install this diagnostic tool on your Microsoft Dynamics NAV Server computer to identify configuration issues that might be preventing your three-tier deployment from working. | Best Practices Analyzer for Microsoft Dynamics NAV 2009 (requires PartnerSource login)

See Also

Concepts

What's New in Application Features for Microsoft Dynamics NAV 2009 SP1
What's New in Microsoft Dynamics NAV 2009 Developer and IT Pro Help


What's New in Application Features for Microsoft Dynamics NAV 2009 SP1

What's New in Application Features for Microsoft Dynamics NAV 2009 SP1
See Also

Microsoft Dynamics NAV 2009 SP1 provides application enhancements to address customer requests, including optimized data entry functions, improved purchase posting in jobs, simpler VAT handling, and various improvements in most application areas.

Note Note

If this service pack version is your first experience with Microsoft Dynamics NAV 2009, then see the topic "What's New in Microsoft Dynamics NAV 2009" in the RoleTailored client Help to read about features that were introduced in the original Microsoft Dynamics NAV 2009 release.

Improved and Enhanced User Experience in the RoleTailored Client

The RoleTailored client has been optimized with the following improvements.

Zoom in on Information Additions

  • About This Page and About This Report features: You can view information about all fields and values that are in the table on which a page or report is based. For example, you may need to know the value of a field that is not displayed on the page but is available in the underlying table. You can click Help, and then click About This Page to see data for the currently selected page.

  • Progress indicator: Now you can easily see how much data has been processed. If the process is taking longer than expected or is no longer needed, then you can press Cancel to stop processing.

Data Entry Enhancements

Several data entry changes have been added to help make you more productive in the RoleTailored client. They include:

  • Calculations in fields: You can enter simple expressions in a field to make calculations in place.

  • Single-cell data copying: You can copy only the data in a cell in a list and paste that value elsewhere, and you can also copy the entire row.

  • Excel-like navigation: In editable lists, you can use arrow keys in the same way as you do in Microsoft Office Excel.

  • Streamlined data entry: You can view and edit data in place in a revised set of forms with matrices. Data entry has been improved to allow easy editing, and the user experience has been made simpler. The set includes:

    • G/L Budget

    • Purchase Budget Overview

    • Sales Budget Overview

    • Resource Capacity

    • Production Forecast

Filtering Improvements

  • Advanced filters: There are improvements in the user experience for choosing fields, so that the options that are presented are narrowed to help you focus on the visible current context but still maintain access to all fields.

  • Search: You can search for pages, report views, and other items with the Search box, just like in Internet Explorer and Outlook. You can also press CTRL+F3 to move the cursor to the Search box quickly.

  • Filter As You Type: Auto completion has been enabled and improved in more places in the RoleTailored client. You can turn off this feature in the Customize This Page dialog box by clearing the Enable automatic filter in lookup fields field. An alternate way of selecting from a list is to press CTRL+F4, which opens a related, relevant list.

Keyboard Shortcut Changes

Keyboard shortcuts have been changed to improve productivity for users of previous versions of Microsoft Dynamics NAV. In addition, new keyboard shortcuts have been added to improve navigation within the RoleTailored client. For example, you can navigate from record to record by pressing the UP ARROW and DOWN ARROW keys to move to the next item in a list and from card to card by pressing CTRL+PAGE UP or CTRL+PAGE DOWN.

Customization and Personalization Changes

Microsoft Dynamics NAV 2009 SP1 introduces several customization improvements to enhance productivity, including:

  • Split box: You can use the split box to control how much information is displayed, such as information in various Role Center parts or in a Lines FastTab.

  • Save View As: Once you set up how you want to see the data that you manage every day, you can save your view of it. Moreover, you can also share your view with your coworkers.

  • Reset user-specified settings: You can easily undo your personalizations and return to the default setup. In your Role Center, click Customize [image] on the menu bar, and then click Delete Personalization Settings.

Online Connect with Community

Microsoft Dynamics NAV 2009 SP1 introduces a Role Center part that connects you with the Internet to provide you with resources such as product updates, newsgroups, online training, and other self-help tools. The types of information that you see are targeted to your role.

For information about the new UI and user experience, see "Learn About the RoleTailored Design" in the RoleTailored client Help.

Application Improvements

Feature improvements and error corrections in Microsoft Dynamics NAV 2009 SP1 include:

Jobs Improvements

  • Better support for jobs in foreign currencies and alignment with sales document functionality; therefore, LCY amount fields are now not editable.

  • Corrected purchase posting in the jobs application area.

  • Improved transparency and traceability after posting purchase orders.

  • Job Ledger Entries reflect an item's actual cost. The Automatic Update Job Item Cost field has been added to the Jobs Setup window. The adjustment process and its results are the same as when you run the Update Job Item Cost batch job.

VAT Improvements

  • Provides a one-to-one relationship between VAT and general ledger entries, which enables efficient general ledger to VAT reconciliation reports. A person in the controller or auditor role can verify each general ledger entry’s corresponding VAT entry and vice versa.

  • Line and Invoice Discount postings have separate VAT specifications and are no longer aggregated into Sales VAT postings. In addition, a table has been added to provide a link between VAT and general ledger entries.

Warehouse Management and Supply Planning Corrections

  • Warehouse granularity

  • Multiple units of measure

  • Partial scenarios with item tracking

Documentation about these improvements and corrections has been included in the Microsoft Dynamics NAV Application Help.

Company Setup Improvements

The Rapid Implementation Methodology (RIM) Toolkit, which helps you quickly implement Microsoft Dynamics NAV, has been improved for Microsoft Dynamics NAV 2009 SP1:

  • Improved import/export function to handle all table data types except Binary, BLOB, Table filter, and Record ID.

  • Added Migration Overview options:

    • Turn on and off validation of table relations.

    • Exclude imported fields from the Apply Data function.

  • Improved error handling so that you can correct errors as they occur in the same context where you can see them.

Microsoft Dynamics NAV Administration

You can only perform certain security and administration tasks using the Classic client. For more information, see "Security, Database, and Other Administration" in the RoleTailored client Help.

See Also

Concepts

What's New in Developing for Microsoft Dynamics NAV 2009 SP1


What's New in Microsoft Dynamics NAV 2009 Developer and IT Pro Help

What's New in Microsoft Dynamics NAV 2009 Developer and IT Pro Help

This topic contains information about the enhancements in Microsoft Dynamics NAV 2009 Developer and IT pro Help in each release.

To download the latest version of the developer Help (cside.chm), IT pro Help (nav_install.chm), and the Security Hardening Guide (Security Hardening Guide.pdf), see the Microsoft Download Center. To view the latest online content in the MSDN Library, see Microsoft Dynamics NAV 2009 Developer and IT Pro Documentation.

Microsoft Dynamics NAV 2009 SP1 Content Release (March 2010)

This section describes the new and updated developer and IT pro Help content in the Microsoft Dynamics NAV 2009 SP1 content release in March 2010. For more information about the improved user experience in the RoleTailored client and application improvements in Microsoft Dynamics NAV 2009 SP1, see the topic What's New in Microsoft Dynamics NAV 2009 SP1 in the RoleTailored client Help.

What's new | See
Web Services Documentation Page operations now discussed in separate reference pages; new page operation (Delete_<part>) now documented; walkthroughs revised. | Working with Web Services
Delegation Added note describing need to configure Microsoft Dynamics NAV Server to delegate to the cifs service on the destination computer in some cases when the destination for a file operation initiated from the RoleTailored client, such as RENAME and COPY, is not on the computer running Microsoft Dynamics NAV Server. | How To: Set Up Delegation
Database Changes that Require Elevated Permissions Updated the information on permissions necessary for various administrator tasks. | Setting Database Owner and Security Administration Permissions
Printing Reports Added a topic about page settings and orientation when you print reports in Microsoft Dynamics NAV 2009 SP1. | Printing Reports
Cues Added a walkthrough that explains how to create and implement a Cue on the Role Center. | Walkthrough: Creating a Cue on a Role Center
Home Button Added a new topic that describes the Home button and how to add items to it. | Home Button Overview
Report Property Reference Added topics about enabling hyperlinks, external images, and external assemblies. | EnableHyperlinks Property EnableExternalImages Property EnableExternalAssemblies Property
ISTEMPORARY Function Added a topic about the ISTEMPORARY RecordRef function | ISTEMPORARY Function (RecordRef)

Microsoft Dynamics NAV 2009 SP1 Content Release (December 2009)

This section describes the new and updated developer and IT pro Help content in the Microsoft Dynamics NAV 2009 SP1 content release in December 2009. For more information about the improved user experience in the RoleTailored client and application improvements in Microsoft Dynamics NAV 2009 SP1, see the topic What's New in Microsoft Dynamics NAV 2009 SP1 in the RoleTailored client Help.

What's new See

Automation

  • Added new topics and updated existing topics about using Automation with the RoleTailored client.

  • Improved Automation walkthroughs

Best Practices for Using Automation With the RoleTailored Client

How to: Create an Automation Controller in C/SIDE

Walkthrough: Using Automation to Write a Letter in Microsoft Office Word

Walkthrough: Using Automation to Create a Graph in Microsoft Excel

Arranging Page Fields Using FixedLayout

Added topics about how to use the FixedLayout control to arrange page fields in rows and columns.

Arranging Fields in Rows and Columns Using a FixedLayout Control

How to: Arrange Page Fields in Rows and Columns Using a FixedLayout Control

Redesigning Matrix Forms

Updated topics to reflect the new redesigned matrix forms in Microsoft Dynamics NAV 2009 SP1. Added a new walkthrough with details about how to redesign a matrix form.

How to: Redesign Matrix Forms

Redesigned Matrix Forms

Walkthrough: Redesigning the Acc. Schedule Overview Form

Multilanguage Functionality

Updated the topics about developing multilanguage-enabled applications and installing language modules.

Working with Multilanguage Functionality

FIND and FINDSET

Added information about when to use the FIND function and when to use the FINDSET function.

C/AL Database Functions and Performance on SQL Server

Code Rules in Form Transformation

Updated existing topic to fix examples and improve clarity.

Code Rules

Web Services Documentation

Added numerous clarifications and enhancements, including a new Web Services Programming Tips topic.

Web Services Programming Tips

Best Practices Analyzer for Microsoft Dynamics NAV 2009

Added references in two topics for this new diagnostic tool, which identifies configuration issues that might be preventing your three-tier deployment of Microsoft Dynamics NAV from working correctly and is available separately as a download.

Walkthrough: Installing the Three Tiers on Three Computers

How To: Set Up Delegation

Configuring Access Control Lists with Microsoft Dynamics NAV 2009 Web Services

Added information to clarify best practices when configuring Web services to use SSL, configuring Web services to use delegation, or configuring Web services to use both SSL and delegation.

Walkthrough: Configuring Web Services to Use SSL

How to: Configure Web Services with Delegation

Microsoft Dynamics NAV 2009 SP1 Content Release (August 2009)

This section describes the new and updated developer and IT pro Help content in the Microsoft Dynamics NAV 2009 SP1 content release in August 2009. For more information about the improved user experience in the RoleTailored client and application improvements in Microsoft Dynamics NAV 2009 SP1, see the topic What's New in Microsoft Dynamics NAV 2009 SP1 in the RoleTailored Client Help.

What's new | See
Language Modules Added topics about how to install language modules and add translated strings in Microsoft Dynamics NAV 2009 SP1. | Working with Multilanguage Functionality
Testing an Application Added topics about using test features in Microsoft Dynamics NAV 2009 SP1. | Testing the Application
Synchronize Logins Added C/AL function topics for new synchronize logins functions | SYNCHRONIZEALLLOGINS Function (Database) SYNCHRONIZESINGLELOGIN Function (Database) SID Function (Database)
C/AL Reserved Words Added list of reserved words in C/AL. | C/AL Reserved Words
C/AL Programming Guidelines Added topics about programming guidelines for formatting, naming, numbering, and other best practices | General C/AL Programming Format Programming Best Practices Naming Conventions Numbering Conventions
Expanded and Improved Web Services Documentation Documentation extensively updated and expanded. New topics address security (SSL) and delegation. Documentation also lists Web service enhancements in Microsoft Dynamics NAV 2009 SP1. | Working with Web Services
Field Text Styling on Pages Added a topic about emphasizing text in a field by changing its color and style. | How to: Style Field Text on a Page
Trigger Reference Added topics about triggers on pages, actions, and codeunits. | OnAction Trigger OnClosePage Trigger OnControlAddin Trigger OnOpenPage Trigger OnQueryClosePage Trigger OnAfterTestRun Trigger OnBeforeTestRun Trigger
Action Images Updated the action image library to include new images that are available in Microsoft Dynamics NAV 2009 SP1. | Action Image Library

Microsoft Dynamics NAV 2009 SP1 Content Release (June 2009)

This section describes the new and updated developer and IT Pro Help content in the Microsoft Dynamics NAV 2009 SP1 content release. For more information about the improved user experience in the RoleTailored client and application improvements in Microsoft Dynamics NAV 2009 SP1, see the topic What's New in Microsoft Dynamics NAV 2009 SP1 in the RoleTailored Client Help.

What's new See

C/SIDE Reference Guide

Added topics about new C/AL functions and properties

IMPORTOBJECTS Function (Codeunit, Dataport, Form, MenuSuite, Page, Report, Table, XMLport)

EXPORTOBJECTS Function (Codeunit, Dataport, Form, MenuSuite, Page, Report, Table, XMLport)

Style Property

StyleExpr Property

Reporting Walkthrough

Adding new walkthrough about linking from a report to a report

Walkthrough: Creating a Link from a Report to a Report

Reporting Troubleshooting

Added a new topic about troubleshooting the Report Designers

Troubleshooting: Classic Client Report Designer and Visual Studio Report Designer

Control and menu IDs on transformed pages

Updated existing topics and added new topics about how to specify control and menu IDs in the transformation input

Transforming Control and Menu IDs

  • How to: Add Actions to a Page By Using Transformation Input

  • How to: Add FactBoxes to Pages By Using Transformation Input

  • How to: Add Home Parts to a Role Center By Using Transformation Input

  • How to: Specify TabControl IDs By Using Transformation Input

Translation strings in transformation input

Added information about exporting translation strings before you transform forms to pages

How to: Create the PageTranslations.txt File

Error List window

Added a topic about compiling objects and using the Error List window

Compiling Objects

Zoom

Added topics about the Zoom feature in the Classic client

Using Zoom

About This Page

Added topics about the About This Page and About This Report features in the RoleTailored client

Using About This Page and About This Report

Multiple Time Zones

Added topics about how Microsoft Dynamics NAV Server can work with RoleTailored clients in multiple time zones.

Communicating with RoleTailored Clients in Different Time Zones

Extending RoleTailored client using control add-ins

  • Added topics about how to use new control add-ins

  • Client extensibility API reference

Extending the RoleTailored Client Using Control Add-ins in Microsoft Dynamics 2009 SP1

Promoted action categories

Added a topic about defining Promoted action categories

How to: Define Promoted Action Categories Captions for the Action Pane

Page Wizard

Added topics about creating pages with the page wizard

How to: Create a Page

Page Designer Run button

Added topics about running pages with the Page Designer Run button

How to: Run a Page

Action Images

Added topics that describe new images that you use on actions

Action Image Library

March 2009 Content Release

What's new See

Debugging with Visual Studio

Added new topics about debugging RoleTailored client objects with Visual Studio.

Debugging C/AL Code

Delegation

Added new topics about setting up delegation

How To: Set Up Delegation

Form Transformation Troubleshooting

Added new topics about troubleshooting pages that you transform with the form transformation tool

Transforming Forms to Pages

Installation Walkthroughs

Updated and improved the topics in this section.

Installation Walkthroughs

Page Designer

Added new topics about:

  • Adding images on actions.

  • Creating activity buttons for the navigation pane.

  • How to: Set an Image on an Action

  • Creating Activity Buttons for the Navigation Pane

Security in the RoleTailored Environment

Added new topics about users, roles, and permissions.

Security in the RoleTailored Environment

Walkthroughs

Added a categorized list of all walkthroughs in the developer and IT Pro help.

Walkthroughs for Microsoft Dynamics NAV 2009

December 2008 Content Release

What's new | See
C/SIDE Reference Updated the C/SIDE reference topics to specify the changes in Microsoft Dynamics NAV 2009. | Changes in C/AL Behavior and Support from Previous Versions of Microsoft Dynamics NAV
Developing for Microsoft Dynamics NAV 2009 Updated content about how to develop for Microsoft Dynamics NAV 2009, including explanations about the differences in developing for the Classic client and the RoleTailored client. | Developing Applications for the Classic Client and RoleTailored Client Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client
File Handling Added new walkthroughs for file handling. | File Handling
Page Designer Updated Page Designer content. | Creating and Maintaining Pages


Microsoft Dynamics NAV 2009 Documentation Roadmap

Microsoft Dynamics NAV 2009 Documentation Roadmap

The following sections provide an overview of how to locate Microsoft Dynamics NAV 2009 documentation for developers and IT professionals. For more information about obtaining the latest version of this content, see Getting Started.

For additional resources that are not part of the Developer and IT Pro Help, see:

  • Microsoft Dynamics NAV Developer Center

  • Microsoft Dynamics NAV 2009 SP1 Technical Training Overview

Developer Documentation

The following is a guide to where you can locate developer documentation for Microsoft Dynamics NAV 2009. For Microsoft Dynamics NAV 5.0, this content was delivered in the w1w1adg.pdf file. For Microsoft Dynamics NAV 2009, it is being delivered in Help format in cside.chm.

For information about | See
Microsoft Dynamics NAV 2009 architecture | Product Architecture for Microsoft Dynamics NAV 2009 in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.
Developing in C/SIDE | C/SIDE Fundamentals Designing C/SIDE Applications Development Considerations
Codeunits | Developing Codeunits
Dataports (Classic client) | Creating Dataports
Forms (Classic client) | Creating and Maintaining Forms
Transforming forms to pages | Transforming Forms to Pages
MenuSuites | Designing MenuSuites
Pages (RoleTailored client) | Creating and Maintaining Pages
Reporting | Designing and Maintaining Reports
Tables | Designing Tables Special C/SIDE Tables
XMLports | Creating XMLports
Multilanguage functionality | Working with Multilanguage Functionality
Performance | Improving Application Performance
Security | Creating a More Secure Application Security in the RoleTailored Environment Microsoft Dynamics NAV 2009 Security Hardening Guide (Security Hardening Guide.pdf) located in the Documentation directory on the Microsoft Dynamics NAV 2009 install media.
Web Services development | Working with Web Services
Other development topics | SumIndexFields Type Conversion Sorting Numerical Values CaptionClass Functionality Multiuser Environments

IT Professional Documentation

The following is a guide to where you can locate IT Professional documentation about Microsoft Dynamics NAV 2009. For Microsoft Dynamics NAV 5.0, this content was delivered in various pdf files. For Microsoft Dynamics NAV 2009, it is delivered in online Help format in nav_install.chm, which is located in the Documentation directory on the Microsoft Dynamics NAV 2009 install media.

For information about | See
Installing Microsoft Dynamics NAV 2009 components | Installation Options and Installing Microsoft Dynamics NAV 2009 in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.
Software and hardware requirements | Microsoft Dynamics NAV 2009 SP1 Requirements in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.
Configuring Microsoft Dynamics NAV 2009 | Configuring Microsoft Dynamics NAV 2009 in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.
Deployment | Installation Walkthroughs in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.

Tabs in the Compiled HTML (CHM) Files

In cside.chm and nav_install.chm, you can look for help on the following tabs:

  • Contents

  • Index

  • Search

  • Favorites

Contents

The Contents tab contains the table of contents. The table of contents lists all topics in the Help. The Help is divided into books that contain related information.

Index

The Index tab contains an alphabetical list of keywords. You can browse the list or type the word for which you are searching.

Search

You can use the Search tab to search for a word or phrase in the Help. You can search for patterns by using wildcard characters. Use the wildcard character "*" to specify zero or more characters in the search string. Use the wildcard character "?" to specify any single character in the search string. For example, to search for topics in the Help that contain either the word "instream" or "outstream", you can enter "*stream" on the Search tab. This pattern matches words that end with stream. To search

Note Note

If you enter more than one search word, then all topics that contain one or more of the words are found. You can narrow a search by typing quotation marks around the search words, such as "filter pane", to only find topics containing that particular phrase.

Favorites

When you find a Help topic that you want to use again, you can add it to your list of favorites. While the topic is displayed in the topic pane, click the Favorites tab, and then click Add. Later, you can select the topic from the list on the Favorites tab, and then click Display.

See Also

Concepts

Getting Started
What's New in Microsoft Dynamics NAV 2009 Developer and IT Pro Help


Tour of the RoleTailored Client for Developers

Tour of the RoleTailored Client for Developers

This section provides a visual overview of the RoleTailored client development environment, including a description of the different windows, pages, parts, and general terminology.

In This Section

RoleTailored Client Design Principle

Touring the RoleTailored Client Windows

Touring the RoleTailored Client Pages


RoleTailored Client Design Principle

RoleTailored Client Design Principle

Design Principle

The RoleTailored client is a customizable user interface that supports the job functions of different work roles in your organization. The RoleTailored client is built around a navigation structure based on a user-centric design. The RoleTailored client is comprised of a number of pages, similar to forms, which contain different information and tasks. The pages are combined in the RoleTailored client and displayed in a series of windows.

RoleTailored client page design principles

In the RoleTailored client, a user starts from a single navigational window called the Role Center that displays information pertinent to his or her role in the company. From the Role Center, the user can navigate to additional information and open separate windows for performing tasks and viewing data. For each role that you support, you can create a Role Center that displays key information and tasks that are required by that role.

See Also

Tasks

Touring the RoleTailored Client Pages
Touring the RoleTailored Client Windows


Touring the RoleTailored Client Windows

Touring the RoleTailored Client Windows
CollapseAll image

The RoleTailored client uses a number of windows to display information. Two of the key window types are the navigation window and task page window. The navigation window is the main window in which users find the information they need to work with. The navigation window is used for the Role Center, List Places, and Departments, as described in this topic. A task page window opens separately from the navigation window when the user selects an action from the navigation window or from other task page windows. It is common for a user to have more than one task page window open at a time.

Expand image Role Center

The Role Center is the main entry point into Microsoft Dynamics NAV 2009. The Role Center opens when the user starts the RoleTailored client. You design the Role Center based on the user's business role, taking into consideration the information and tasks relevant to the user during a typical work day.

RoleTailored client RoleCenter example

You create a Role Center by using a Role Center page. The Role Center page opens in the navigation window. Usually, there will only be a single navigation window open at a time. From there, users can open any number of task windows. The content area displays the Role Center page. The navigation pane includes a menu that links to List Places and Departments.

For more information, see the following.

To | See
Learn how to create a Role Center page | Walkthrough: Creating a Role Center
Get an overview of the parts on a role Center page | Touring the RoleTailored Client Pages
Get an overview of the navigation window layout and its parts | Navigation Window

Expand image List Places

A List Place displays information from a table in a list format with rows and columns. Typical uses for List Places include displaying sale orders or customers. Similar to the Role Center, List Places display in the navigation window, including the navigation pane.

RoleTailored client List Place page example

List Places only open from the menu items in the navigation pane. To create a List Place, you create List type and then include the List Place in the navigation pane by adding actions to the Role Center page using the Action Designer to create the menu items in the navigation pane.

For more information, see the following.

To | See
See an example of how to create a List page Role Center page | Walkthrough: Creating a Customer List in Page Designer
Learn about List pages and parts, including FactBoxes | Touring the RoleTailored Client Pages
Get an overview of the navigation window layout and its parts | Navigation Window

Expand image Departments

The Departments item in the navigation pane of the RoleTailored client provides links to all the pages of the RoleTailored client. The links and pages under Departments are generated automatically based on the menu suite of the RoleTailored client user.

RoleTailored client Departments example

To make changes to Departments, you change the menu suite.

For more information, see the following.

To | See
Learn how to change the menu suite | Designing MenuSuites
Get an overview of the navigation window layout and its parts | Navigation Window

Expand image Navigation Window Overview

The following illustration outlines the parts of the navigation window that are used by Role Centers, List Places, and Departments.

RoleTailored client Navigation Window overview

Content Area

The content area displays the content of a Role Center page, List page, or Department.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Get an overview of the pages | Touring the RoleTailored Client Pages

Navigation Pane

The navigation pane displays a menu that links different pages of the RoleTailored client. Menu items are arranged in a hierarchical structure that allows the user to drill down through the different levels of menu items.

You use the navigation pane to link to the different List Places of the RoleTailored client. To create menu items in the navigation pane, you add actions to the Role Center page using the Action Designer. You can include menu items under Activity buttons (such as the Home button). You can also add additional buttons, such as Posted Documents, and include the menu items there. The Departments button and its menu items are generated automatically based on the Microsoft Dynamics NAV menu suite.

For more information, see the following.

To | See
See an overview of actions | Actions Overview
Learn how to add actions to a page | How to: Add Actions to a Page
See an example of how to add an action to the navigation pane | Walkthrough: Creating a Role Center

Address Bar

The address bar displays the location of the current page within the navigation hierarchy of the application. The Address bar updates when the user navigates to a different page.

Note Note

The Address bar is not configurable.

Status Bar

The status bar displays information about the current state of the RoleTailored client session, including the name of the company, the date and, the user's name or ID.

For users who work with more than one company, the status bar provides access to all the companies that they work with. By clicking the company name, the user can open a drop-down list which shows the companies available to them. Users can switch between companies.

Note Note

The status bar is not configurable.

Expand image Task Window

A Task window opens separately from the navigation window when a user clicks an action or menu item. A Task window typically shows a single object or element such as a task, list, or report. Common uses of Task pages include creating or editing sales orders, customer details, and items. The following illustration shows a Task window that displays a Card page for editing customers.

RoleTailored client Card page example

Task pages are similar in concept to the pop-up windows in Microsoft Office Outlook that show an e-mail, contact, or a task. It is typical for users to have multiple task pages open at the same time. Similar to the navigation window, a Task window includes a Command bar and Action pane. Unlike the navigation window, it does not include the navigation pane or status bar. The user can work with more than one Task window open at a time.

You create a Task window by creating a page and then linking the page to actions on other pages. The most common page types for Task windows are Card, Document, and List.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Get an overview of the pages | Touring the RoleTailored Client Pages

Expand image See Also

Tasks

Touring the RoleTailored Client Pages


Touring the RoleTailored Client Pages

Touring the RoleTailored Client Pages

In Microsoft Dynamics NAV, pages replace forms as the main way to display and organize data in the RoleTailored client. You can create pages to offer users a visual experience that is closely aligned to Microsoft Office and Windows Vista. There are different page types that you use for different situations. The page type you choose depends on the application task you want to support, the content you want to display, and how you want to display it. For example, the Role Center page is the main page of the RoleTailored client and it displays when the RoleTailored client opens. The Role Center page is similar to a home page that helps users focus on their most important daily activities, by giving an overview of the information relevant to their tasks on one page. Other types of pages, such as List pages, display lists of customers or sales orders, while others such as Document task pages, focus on user tasks.

Expand image Designing Pages

You create page objects in Page Designer of the Object Designer, similar to the way you save forms or other Microsoft Dynamics NAV objects. In the Page Designer, a page is basically an XML object composed of a number of XML elements that determine the layout and the page content. The following illustration shows an example of the Page Designer.

Page Designer overview

To add content to a page, you add containers that divide the page into separate areas which add different parts and content to the page. Each page type has a specific set of controls that can be used with that page type. For example, Cues can only be used on Role Center pages and FastTabs can only be used on Card and Document pages. The card page type shows a number of different controls used on one page type. It includes FastTabs, FactBoxes, Actions, and Action Pane controls.

For more information, see the following.

To | See
Learn how to use the Page Designer to create pages | Creating and Maintaining Pages

Expand image Role Center Page Type

The Role Center page is the main page of the RoleTailored client. You can customize the Role Center page for the individual user. The Role Center page provides the user with an overview of the day’s work, where the user can quickly access information and tasks on which to focus for the day.

RoleTailored client RoleCenter page type example

The Role Center page uses Cues and system parts, including My Notes, Outlook, and Recorder links.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Go through an example of how to create a Role Center page | Walkthrough: Creating a Role Center
Get more information about Cues | Cue

Expand image Card Page Type

A Card page is used to view and edit one record or entity from a table. The Card page displays selected fields from the table. An example of using a Card page is for editing a customer.

RoleTailored client Card page example

You can group one or more fields in FastTabs. You can also include a FactBox that displays additional information about the record in the page.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Go through an example of how to create a card page | Walkthrough: Creating a Customer Card Page in Page Designer
Get more information about FactBoxes | FactBox
Get more information about FastTabs | FastTab

Expand image Card Part Page Type

A Card Part page is used in a FactBox on another page to view or edit additional fields associated with a selected entity in the page. The following illustration shows an example of using a Card Part page on a List page that displays sales orders. In the FactBox on the right, a CardPart page displays details about the customer that placed the selected sales order.

RoleTailored client Card page example

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Go through an example of how to use a card part on a Role Center page | Walkthrough: Creating a Role Center
Go through an example of how to use a CardPart page in a FactBox | How to: Create a FactBox to Display Customer Data
Get more information about FactBoxes | FactBox
Get more information about FastTabs | FastTab
See a CardPart page in Object Designer | The page called Customer Details FactBox with ID 9084

Expand image ConfirmationDialog Page

You use the ConfirmationDialog page to display messages or prompt users with a confirmation before they continue with the task that they are working on. For example, when filling out a sales order, a user can select a quantity for an item. This quantity might exceed the item's availability. Using a ConfirmationDialog page, you can display a message that indicates this condition to the user. The user can then choose to continue or cancel filling out the sales order.

RoleTailored client Confirmed Dialog page example

To create a ConfirmationDialog, you define the message and table fields that you want displayed.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
See a Confirmation page in Object Designer | The page called Check Availability with ID 342

Expand image Document Page Type

A Document Page usually consists of two separate pages combined into one, with one page nested in the other. A Document Page is suitable for use when you want to display data from two tables that are linked together. This is the case, for example, with sales orders, which have two source tables: Sales Header and Sales Lines. The following illustration shows a sales order that is created using a Document page type.

RoleTailored client Document page example

A Document page displays a FastTab at the top of the page for showing fields, followed by another FastTab with line items for the selected item. Optionally, you can add additional FastTabs to display more details about a selected item.

Note Note

The Header and Line form in the Classic client provides similar functionality by combining a main form with a subform.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Go through an example of how to create a Document page | Walkthrough: Creating a Document Page
Get more information about FastTabs | FastTab
See a Document page in Object Designer | The page called Sales Order with ID 42

Expand image List Page Type

A List page displays content from a table in a list format. List pages can display as List Places (as part of the navigation layer) or in Task pages.

RoleTailored client sales order List page example

You can also add a FactBox to display additional information about a selected item in the list.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Go through an example of how to create a List page | Walkthrough: Creating a Customer List in Page Designer
Learn more about List Places | Touring the RoleTailored Client Windows
Get more information about FactBoxes | FactBox
See a List page in Object Designer | The page called Sales Order List with ID 9305

Expand image List Part Page Type

Similar to a List page, a List Part page displays content from a table in a list format. The difference is that you use the List part page as another page in a FactBox or as a part of the Role Center page. The following illustration shows a List Part page that is used in the Role Center for showing a list of the user's customers.

RoleTailored client ListPart page example

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Get more information about FactBoxes | FactBox
See how a List Part page is used on a Role Center page | The page called Order Processor Role Center with ID 9006

Expand image Navigate Page Type for Wizards

You use a Navigate page type to create a wizard that leads the user through a sequence of steps for completing a task.

RoleTailored client Navigation pane wizard example

A wizard opens as a Task page.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Go through an example that creates a Navigate Page | Walkthrough: Creating a Wizard Page
Learn more about task pages | Touring the RoleTailored Client Windows
See a Navigate page that is used as a wizard in Object Designer | The page called Create To-do with ID 5097.

Expand image Worksheet Page

You use a Worksheet page type for creating worksheet or journal task pages. The Worksheet page consists of a single grid in the content area and a section at the bottom with details about the selected grid line or totals for the grid.

RoleTailored client navigation page example

You can optionally include a FactBox.

For more information, see the following.

To | See
Learn how to create a page | How to: Create a Page
Go through an example that creates a Worksheet Page | Walkthrough: Creating a Worksheet Page
Get more information about FactBoxes | FactBox
See a Worksheet page | The page called Standard Cost Worksheet with ID 5841

Expand image Page Controls and Parts

Action Pane

The Action pane is located under the Command bar on task pages and list places and contains shortcuts to actions. Actions display as icons which the user can click to complete a task or view information.

Action Pane clip from a Customer List page

To include an action in the Action pane, you use the Action Designer (available from the View menu when a Page Designer window is open) and promote the action. You should use the Action pane to display the tasks most frequently used by the user in the context of the page. For example, on a List page that displays sales orders, you should promote the action to process a sales order to the Action pane.

For more information, see the following.

To | See
Learn more about actions and navigation | Adding Actions to Pages
Learn how to promote actions to the action page | How to: Add Actions to the Action Pane on Pages
See a page that promotes actions to the Action pane | The page called Customer List with ID 22

Command Bar

The command bar displays a menu of actions at the top of a page that the user can click to perform additional tasks or view information.

RoleTailored client command bar example

To create a menu item in the Action pane, you add an action on the page. You can choose to include the action under three different menu items: Actions, Related Information, and Reports. Depending on the page type, the Action pane will automatically include default actions, such as View, Edit, New, and Delete.

For more information, see the following.

To | See
Learn more about actions and navigation | Adding Actions to Pages.
Learn how to add an action to the Command bar | How to: Add Actions to a Page.
See a page that has actions in the Command bar | The page called Customer List with ID 22

Cue

A Cue is an icon that provides a shortcut link to an underlying filtered list, such as invoices, sales orders, or credit memos. A Cue icon depicts a stack of papers on the page, where the height of the stack roughly indicates the number of entities in the underlying list. A number value on each Cue gives the precise count.

RoleTailored client cue example

A Cue can only be used on a Role Center page.

For more information, see the following.

To | See
Learn how to create a Cue | Walkthrough: Creating a Cue on a Role Center
Go through an example that uses a Cue on the Role Center | Walkthrough: Creating a Role Center
See a page that uses Cues | The page called SO Processor Activities with ID 9060

Chart Pane

The Chart pane displays data from a list in graphic form, giving the user a visual overview of the value distribution. Chart panes are only available on List page types.

RoleTailored client Chart part example

To view a chart pane, click Customize on the page's command bar, and then select Chart Pane. To change the data that is displayed in a chart, click Measures or Dimensions, and then select to the fields that you want.

For more information, see the following.

To | See
See a chart pane on a List page | The page called Sales Order List with ID 9305.

FactBox

A FactBox is an area that is located on the right side of a page which displays data related to information about an item on the page. For example, on a list page that shows sales orders, you can use a FactBox to show additional fields of a selected sales order in the list.

RoleTailored client FactBox example

You can set a FactBox to display a page, system part, or a chart. If you set the FactBox to display a page, you can display the following page types:

  • Card

  • List

  • List Plus

  • Document

  • Worksheet

  • Navigation

For more information, see the following.

To | See
Go through an example that uses a FactBox | Walkthrough: Adding a FactBox to the Customer List Page
See a page that uses a FactBox | The page called Sales Order List with ID 9305

FastTabs

FastTabs enable you to place data in separate groups on a page, where each group has a header that expands and collapses the group when clicked. The header of the FastTab displays a name, such as "Prepayment" on the Sales Order shown. You can also promote fields included on the FastTab to the header. Promoting a field to the header enables you to present key information to the user when the FastTab is collapsed.

RoleTailored client FastTab example

Organizing data using FastTabs helps users to find key information more quickly, while giving an overview of areas that otherwise would remain hidden.

For more information, see the following.

To | See
Learn how to add a FastTab to a page | How to: Add FastTabs to a Customer Card Page
See a page that uses a FastTabs | The page called Sales Order with ID 42

Filter Pane

The Filter pane is found on List pages and enables the user to filter and sort the items displayed in the list based on a given criteria.

RoleTailored client filter pane example

The Filter pane is automatically included on List pages and cannot be configured.

Outlook Part

The Outlook part gives users an overview of the e-mails, calendar, and tasks that are found in their Microsoft Outlook account without having to open Outlook.

RoleTailored client Outlook Part featured

The Outlook part is suitable for most page types and very useful on the Role Center. The Outlook part is a system part that you can use directly on a page or in a FactBox.

For more information, see the following.

To | See
Go through an example that uses the Outlook control | Walkthrough: Creating a Role Center
See a page that uses the Outlook control | The page called Order Processor Role Center with ID 9006

My Notes

The My Notes part allows users to view notifications that are assigned to them, similar to messenger service. The notifications are generated from a Notes control on a task page. For example, on sales order page, the user can add a note and then target another user to receive the note. This note then shows up in the target user's My Notifications.

RoleTailored client MyNotifications part example

By double-clicking the link to the note in the notification, users can navigate directly to the relevant Task page to deal immediately and directly with the urgent issue or exceptions.

The My Notes part is designed to be used on a Role Center page.

For more information, see the following.

To | See
Go through an example that uses My Notes | Walkthrough: Creating a Role Center
See a page that uses the My Notes part | The page called Order Processor Role Center with ID 9006

Notes

The Notes part allows the user to attach a note to an item on a Task page. For example, when creating a sales order, a user can add a note about the order. The note will appear with the item when it is viewed. If another user is targeted to be notified, then the note will appear in that user's Role Center in the My Notification part.

RoleTailored client Notes part example

You use Notes in a FactBox on a page.

For more information, see the following.

To | See
See a page that uses a Notes part | The page called Sales Order with ID 42

RecordLinks

The RecordLinks part allows the user to add links to files on items on a Task page. For example, when creating a sales order, users can add a link to the Microsoft Word document that pertains to the order. The links will appear with the item when it is viewed. When a user clicks a link, the target file opens.

RoleTailored client recorded links example

You use RecordedLinks in a FactBox on a page.

For more information, see the following.

To | See
See a page that uses a RecordedLinks part | The page called Sales Order with ID 42

Expand image See Also

Tasks

Touring the RoleTailored Client Windows


Walkthroughs for Microsoft Dynamics NAV 2009

Walkthroughs for Microsoft Dynamics NAV 2009

The Microsoft Dynamics NAV 2009 Developer and IT Pro Help contains walkthrough topics that show you step-by-step procedures to perform all tasks in a developer or IT Pro scenario. You can use the CRONUS International Ltd. demo database to walk through these scenarios and learn about Microsoft Dynamics NAV 2009.

The following tables list all the walkthroughs in the Microsoft Dynamics NAV 2009 Developer and IT Pro Help.

Installation and Configuration Walkthroughs

Walkthrough: Installing the Demo Version

Walkthrough: Installing the Three Tiers on Three Computers

Walkthrough: Installing the Three Tiers On Two Computers

Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer

Walkthrough: Configuring the Order Processor Role Center

Walkthrough: Personalizing the Order Processor Role Center

Walkthrough: Synchronizing Information Between Outlook and Microsoft Dynamics NAV

Administration Walkthroughs

Walkthrough: Setting Up Document Approvals

Walkthrough: Setting Up Outlook Synchronization

Object Development Walkthroughs

Page Designer Walkthroughs

Walkthrough: Transforming a Standard Application Form

Walkthrough: Redesigning the Acc. Schedule Overview Form

RoleTailored Client Report Walkthroughs

Classic Report Walkthroughs

Walkthrough: Redesigning a Customer List Report

Walkthrough: Redesigning a Customer - Order Summary Report

Walkthrough: Using Codeunits

Walkthrough: Creating a Dynamic Dataport

Web Services Walkthroughs

Walkthrough: Creating a Web Service using Extension Codeunits

Walkthrough: Creating and Consuming a Codeunit Web Service

Walkthrough: Registering and Consuming a Page Web Service

Walkthrough: Configuring Web Services to Use SSL

RoleTailored Client Control Add-in Walkthroughs

Walkthrough: Creating and Using a RoleTailored Client Control Add-in

File Handling Walkthroughs

Walkthrough: Uploading a File from a Client to Microsoft Dynamics NAV Server

Walkthrough: Transferring a File from Microsoft Dynamics NAV Server to the Client

Automation Walkthroughs

Walkthrough: Receiving Events in C/SIDE

Walkthrough: Using Custom Controls from C/SIDE

Walkthrough: Using Automation to Write a Letter in Microsoft Office Word

Walkthrough: Using Automation to Create a Graph in Microsoft Excel

Debugging and Testing Walkthroughs

Walkthrough: Debugging an Action on a Page

Walkthrough: Testing Vendor Discount

See Also

Concepts

Getting Started


Copyright and Trademarks

Copyright and Trademarks

Notices

Complying with all applicable copyright laws is the responsibility of the user. Microsoft grants you the right to reproduce this documentation, in whole or in part, specifically and solely for your internal, reference purposes.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, trade dress, copyrights, or other intellectual property.

Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred.

Trademarks

Microsoft, C/SIDE, Microsoft Dynamics, Navision, SQL Server, Visual Studio, Windows, Windows Server, Windows Vista, and/or other Microsoft products or services mentioned herein are trademarks of the Microsoft group of companies. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


Install and Configure Microsoft Dynamics NAV 2009 SP1

Install and Configure Microsoft Dynamics NAV 2009 SP1

Microsoft Dynamics NAV 2009 is a business management solution for small and midsized organizations that helps simplify and streamline highly specialized business processes, rapidly adapting to the unique requirements of individual businesses. Microsoft Dynamics NAV 2009 provides industry specific functionality that is relevant to the local needs of regions of operation, even for the most highly specialized industries and organizations.

Audience

The Install and Configure Microsoft Dynamics NAV Help is for partners and administrators who are responsible for installing and configuring Microsoft Dynamics NAV.

Key Features of Setup

With Microsoft Dynamics NAV Setup, you can:

  • Install different components on different computers.

  • Choose from a selection of predefined Installation Options or create your own custom list of components and options to install. For more information, see How to: Choose Components to Install.

  • Preconfigure components before installation. For more information, see How to: Preconfigure Components.

  • Create, save, or load Setup configuration files that capture your selection of components and configuration information. For more information, see How to: Create or Load a Setup Configuration File.

You can use Setup to install software and to create custom deployments that you can distribute to different users across a company.

Tasks Described in the Installation and Configuration Help

Use the Install and Configure Microsoft Dynamics NAV Help to:

  • Learn about the architecture of Microsoft Dynamics NAV. Learn how different sets of components interact and what you must do to ensure that the various components work together effectively.

  • Determine the hardware and software that is required on a computer before you install Microsoft Dynamics NAV 2009 components.

  • Preconfigure individual components.

  • Configure computers to allow Microsoft Dynamics NAV components to interact correctly.

Installation Notes

  • Before installing Microsoft Dynamics NAV 2009 Service Pack 1 on a computer, you must remove other versions of Microsoft Dynamics NAV. You cannot upgrade previous versions of Microsoft Dynamics NAV to Microsoft Dynamics NAV 2009 SP 1 without uninstalling previous versions.

  • All RoleTailored components in an organization must be from the same version and build of Microsoft Dynamics NAV for the software to run correctly.

  • Installing more than one copy of Microsoft Dynamics NAV on a single computer is not supported. The exception is for installing more than one instance of Microsoft Dynamics NAV Server, but this installation requires special steps. See Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer.

  • Installing with individual .msi files, which was a supported scenario in earlier versions of Microsoft Dynamics NAV, is not supported in Microsoft Dynamics NAV 2009.

  • You can find information about migrating data from a classic C/SIDE database to SQL Server in the Microsoft Dynamics NAV Upgrade Toolkit manual. You can find the toolkit appropriate for your locale on the Product Downloads for Microsoft Dynamics NAV 2009 page (requires PartnerSource log-in).

  • If you have either SQL Server 2000 or Microsoft SQL Server Desktop Engine (MSDE) installed on a computer where you want to install Microsoft Dynamics NAV 2009, then you must remove it before you begin installing. The presence of either of these database products causes a Setup error.

See Also

Concepts

Installing Microsoft Dynamics NAV 2009
Configuring Microsoft Dynamics NAV 2009

Other Resources

Product Architecture for Microsoft Dynamics NAV 2009
Installation Options
Microsoft Dynamics NAV 2009 SP1 Requirements


Accessing the Latest Install and Configure Help

Accessing the Latest Install and Configure Help

The latest version of the Microsoft Dynamics NAV 2009 Installation and Configuration Help is always available in the MSDN Library. This Help is refreshed on MSDN every few months.

To download the latest version of the Microsoft Dynamics NAV 2009 Installation and Configuration Help, visit the Microsoft Download Center.

See Also

Concepts

Installing Microsoft Dynamics NAV 2009


Product Architecture for Microsoft Dynamics NAV 2009

Product Architecture for Microsoft Dynamics NAV 2009

Three separate types of components are included in Microsoft Dynamics NAV 2009.

In This Section

  • RoleTailored Architecture

    These components are new in Microsoft Dynamics NAV 2009 and work together to create a more secure, flexible, and efficient user experience.

  • Classic Architecture

    These components are familiar to users of earlier versions of Microsoft Dynamics NAV 2009 and are still relevant for development and administration in Microsoft Dynamics NAV 2009.

  • Additional Components

    These components are not part of either core architecture but are still useful and important for some customers.


RoleTailored Architecture

RoleTailored Architecture

RoleTailored architecture components are new with Microsoft Dynamics NAV 2009. They work together to make the product more flexible, efficient, scalable, and secure, while also improving the user experience.

The Three Tiers of the RoleTailored Architecture

The RoleTailored architecture is a three-tiered architecture which contains the following levels:

  • Presentation level (RoleTailored client)

  • Business logic and communication level (Microsoft Dynamics NAV Server)

  • Data level (SQL Server database)

The different tiers can be installed on different computers. You can have multiple instances of any of the components (though usually not on the same computer): multiple clients, multiple servers, and multiple database servers.

Here's a simple installation with two SQL Server database computers, each associated with a single Microsoft Dynamics NAV Server computer, each of which in turn supports two Microsoft Dynamics NAV RoleTailored clients:

The RoleTailored architecture.

RoleTailored Architecture Components

The components that make up the RoleTailored architecture in Microsoft Dynamics NAV 2009 are:

  • RoleTailored Client

  • Microsoft Dynamics NAV Server

  • Database Components and SQL Server

Note Important

All RoleTailored components in an organization must be from the same version and build of Microsoft Dynamics NAV for the software to run correctly.

Compatible with Classic Architecture

The RoleTailored architecture and the Classic architecture are not mutually exclusive. In fact, the Classic client remains an essential component for developing and administering Microsoft Dynamics NAV applications. For example, you must use the Classic client to upload your Microsoft Dynamics NAV 2009 license file.

Companies migrating from Microsoft Dynamics NAV 2009 typically migrate applications and users to the RoleTailored architecture over time, as resources and needs dictate. The two architectures can be used side-by-side without problems.

See Also

Concepts

Classic Architecture


RoleTailored Client

RoleTailored Client

Microsoft Dynamics NAV 2009 provides an intuitive and customizable user interface called the RoleTailored client, which developers, partners, administrators, and super users can customize to support the job functions of different work roles in an organization.

For each role within an organization, the Microsoft Certified Partner or developer creates a customizable Role Center that displays key information required for relevant employees and makes their day-to-day tasks easier to complete. Users run the RoleTailored client to find the information and data entry points their jobs require.

For example, partners and developers can customize the sales order processor Role Center to display an interactive list of customers, daily activities, and sales information, and also give users easy access to their Microsoft Office Outlook e-mail, tasks, and calendar, all within the RoleTailored client.

The RoleTailored client is installed when you select either the Client Option or the Developer Environment Option in Microsoft Dynamics NAV Setup.

See Also

Concepts

Client Option Requirements
Configuring the RoleTailored Client


Microsoft Dynamics NAV Server

Microsoft Dynamics NAV Server

Microsoft Dynamics NAV Server is a .NET-based Windows Service application that works exclusively with SQL Server databases. It uses the Windows Communication Framework as the communication protocol for RoleTailored clients and for Web services. It can execute multiple client requests in parallel and serve other clients by providing Web service access to authenticated clients.

A key difference between the two-tier architecture with the Classic client and three-tier architecture with the RoleTailored client and Microsoft Dynamics NAV Server is that business logic runs on the server instead of the client in the three-tier architecture. A simple example is the FILE.CREATE function. In previous versions of Microsoft Dynamics NAV, files are created on the client when code is run. With the RoleTailored architecture, the files are created on the service itself.

Microsoft Dynamics NAV Server provides an additional layer of security between the clients and the database. It leverages the authentication features of the Windows Communications Framework to provide another layer of user authentication and uses impersonation to ensure that business logic is executed in a process that has been instantiated by the user who submitted the request. Authorization and logging of user requests is still performed on a per-user basis. This ensures that all Windows authentication and Microsoft Dynamics NAV roles and permissions that have been granted to the user are correct. It also ensures that business logic–level auditing is still performed.

Microsoft Dynamics NAV Server is installed when you select either the Server Installation Option or the Developer Environment Installation Option in Microsoft Dynamics NAV Setup.

Note Note

Installing Microsoft Dynamics NAV Server on encrypted drives is not supported. You may run into issues if the server runs as a user that does not have access rights to the encrypted files.

Note Note

For certain Automation tasks, you must run Microsoft Dynamics NAV Server with administrator permissions.

See Also

Concepts

Server Option
Server Option Requirements
Configuring Microsoft Dynamics NAV Server
Enhancing Microsoft Dynamics NAV Server Security


Communicating with RoleTailored Clients in Different Time Zones

Communicating with RoleTailored Clients in Different Time Zones
See Also

Microsoft Dynamics NAV Server can interact with RoleTailored clients in different time zones.

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Implementation

If the client data contains data of the type DateTime, then upon receiving the data from the client, Microsoft Dynamics NAV Server converts this data into Coordinated Universal Time (UTC) based on the client time zone. When passing data of type DateTime back to the client, Microsoft Dynamics NAV Server converts the time back to the local time zone of the client before presenting the data to the end user.

Different countries and regions sometimes have different rules for determining when and if to start and end Daylight Saving Time. If computers running Microsoft Dynamics NAV Server computers are kept current with Windows updates, then changes to Daylight Saving Time are managed automatically.

Note Note

There is limited support for reading and writing in UTC in the RoleTailored client. Specifically, the client evaluates and formats DateTime values in forms and pages using format code 9. This format is UTC but can be difficult to read. For example, the format is 2008-01-01T10:22:00Z.

Web Services Originating from Different Time Zones

Microsoft Dynamics NAV Server cannot determine the time zone of origin for a Web service. Therefore, all Web server communication should be in UTC. All business logic is executed with respect to UTC.

See Also

Concepts

Configuring the RoleTailored Client


Microsoft Dynamics NAV Web Services (Microsoft Dynamics NAV Server)

Microsoft Dynamics NAV Web Services (Microsoft Dynamics NAV Server)
See Also

When you install Microsoft Dynamics NAV Server on a computer, you automatically install the Microsoft Dynamics NAV Business Web Services service, which is a Windows service.

Use this service to establish communication between external processes and applications and Microsoft Dynamics NAV 2009. Web service integration with Microsoft Dynamics NAV is supported through Web service–enabled pages and codeunits. With proper authentication and authorization, external systems can read and write data on pages and call codeunits as defined by the common Web service protocols. When pages and codeunits are published as Web services from Microsoft Dynamics NAV, they are immediately available for Web service requests over the network.

Different Types of Web Services

Microsoft Dynamics NAV supports exposing either pages or codeunits as Web services. You can also use extension codeunits to extend the default set of methods that are available on a page. This enables you to perform operations other than standard page operations.

See Also

Other Resources

Working with Web Services


Database Components

Database Components

The Database Components installation option in Setup installs the software that configures the Microsoft SQL Server database to work with Microsoft Dynamics NAV 2009.

If SQL Server is not present on the computer where you install the database components, Setup installs SQL Server Express 2005, which is an appropriate database option for prototyping and testing, but will likely prove inadequate for all but the smallest production environments.

Database components are installed when you select the Database Components Installation Option in Microsoft Dynamics NAV Setup.

See Also

Concepts

Database Components Option
Database Components Option Requirements
Configuring Database Components


Classic Architecture

Classic Architecture

The Classic architecture is a term that describes the components carried forward from the 5.0 version of Microsoft Dynamics NAV.

Microsoft Dynamics NAV 2009 customers can opt to migrate to the new architecture immediately, gradually, or not at all. Microsoft has designed Dynamics NAV 2009 so that the Classic and RoleTailored architectures, and their respective components, can co-exist without conflict within a single organization.

Within the Classic architecture, the Classic client connects to either a Microsoft SQL Server database server or to a Classic database server (the proprietary NAV database server). In the RoleTailored architecture, SQL Server is the only database server.

The Classic client is the one Classic component that remains essential for all Microsoft Dynamics NAV 2009 installations, as a tool for development and administration tasks. For example, you must use the Classic client to upload your Microsoft Dynamics NAV 2009 license file.

Classic Architecture Components

The components that make up the Classic architecture in Microsoft Dynamics NAV 2009 are:

  • Classic Client

  • Classic Application Server

  • Classic Database Server

See Also

Concepts

RoleTailored Architecture


Classic Client

Classic Client

The Classic client is a Classic Architecture component in Microsoft Dynamics NAV 2009. The Classic client was the only client in earlier versions of Microsoft Dynamics NAV. It remains a viable option for interacting with Microsoft Dynamics NAV applications and data.

The Classic client runs business logic locally, and displays data in forms, such as card forms or list forms. You design forms in a visual design environment with precise layout information.

You can migrate users and applications from the Classic client to the RoleTailored client. Microsoft Dynamics NAV 2009 is designed to accommodate both types of clients in parallel.

The Classic client is installed when you select either the Client Installation Option or the Developer Environment Installation Option in Microsoft Dynamics NAV Setup.

See Also

Concepts

Client Option
Developer Environment Option
Client Option Requirements
Developer Environment Option Requirements


Classic Application Server

Classic Application Server

The Classic Application Server is a Classic Architecture component in Microsoft Dynamics NAV 2009. It is not the same as the NAV Server, which is a RoleTailored Architecture component.

If you are maintaining clients and applications under the Classic architecture, you may need to have Application Server available for communication with certain processes and functionality, such as Microsoft Office Outlook Integration. The NAV Application Server is installed by Setup as part of the Classic Server Components installation option.

For information on how to start Classic Application Server or set up communications between the Classic client and Classic Application Server, see NAV Application Server in the C/SIDE Reference Guide.

For additional information about the Classic Application Server, see w1w1atas.pdf ("Installation & System Management: Application Server for Microsoft Dynamics NAV"). To obtain this manual, go to the Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download w1w1atas.pdf. Disregard all information in the PDF on how to install Classic Application Server—that information is superseded by information in this Help system.

See Also

Concepts

Classic Server Components Option
Classic Server Components Option Requirements


Classic Database Server

Classic Database Server

The Classic database server, also known as the C/SIDE database server, is a proprietary database server developed for earlier versions of Microsoft Dynamics NAV.

Note Note

The Classic database service does not interact with RoleTailored Architecture components.

The Classic database server is a Classic Architecture component in Microsoft Dynamics NAV 2009. However, it is not a required element of the Classic architecture; you can use the Classic client with Microsoft SQL Server as your database server. But if you have existing data on a Classic database server, and you do not plan to migrate this data to SQL Server, you can continue using the Classic database server in Microsoft Dynamics NAV 2009, though this restricts you to using Classic architecture components.

The Classic database server is installed by Setup as part of the Classic Server installation option.

Classic Database Server Documentation

For additional information about the Classic database server, including information on configuration, see w1w1ism.pdf ("Installation & System Management: C/SIDE Database Server for Microsoft Dynamics NAV "). To obtain this manual, go to the Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download w1w1ism.pdf. Disregard all information in the PDF on how to install Classic database server—that information is superseded by information in this Help system.

See Also

Concepts

Classic Server Components Option
Classic Database Server Requirements


Additional Components

Additional Components

The components listed in this section extend the capabilities of Microsoft Dynamics NAV 2009 in various ways. None of these components are new with Microsoft Dynamics NAV 2009. All of these components require Classic Application Server, which is part of the Classic Architecture in Microsoft Dynamics NAV 2009.

Components

The additional components available with Microsoft Dynamics NAV 2009 are:

  • Automated Data Capture System

  • Commerce Gateway

  • Business Notification

See Also

Concepts

Classic Architecture

Other Resources

Microsoft Dynamics NAV 2009 SP1 Requirements


Automated Data Capture System

Automated Data Capture System

The Automated Data Capture System (ADCS) is a Microsoft Dynamics NAV tool that gives companies the ability to accurately capture data for inbound, outbound, and internal documents, primarily in connection with warehouse activities. With ADCS, company employees use handheld devices and radio frequency technology to continuously validate warehouse inventories.

Installing ADCS

To install ADCS, you must customize the list of components to install to include ADCS, which is not included in any of the predefined Installation Options. For more information, see How to: Choose Components to Install.

ADCS requires Classic Application Server, which is part of the Classic Architecture in Microsoft Dynamics NAV 2009.

ADCS Documentation

For more information about ADCS, see the ADCS manual, w1w1InstADCS.pdf ("Automated Data Capture Systems for Microsoft Dynamics NAV"). To obtain this manual, go to Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download w1w1InstADCS.pdf.

Note Note

Use the PDF only for configuration information. The installation information in the manual is superseded by the "Installing ADCS" section, above.

See Also

Tasks

How to: Run Setup

Concepts

Automated Data Capture System Requirements
Configuring Automated Data Capture System


Commerce Gateway

Commerce Gateway

With Commerce Gateway, companies can use Microsoft Dynamics NAV 2009 to electronically exchange trading documents with business partners regardless of conversion requirements and data formats. This can help streamline business processes and reduce transaction costs. Commerce Gateway also makes it easier for companies to meet the changing demands of their trading partners, regardless of the industry they are in, the system that they use, or the standards that their partners require.

Commerce Gateway provides integration with Microsoft BizTalk Server, a data and business process integration server that facilitates e-commerce business processes. Microsoft BizTalk Server comprises a document interchange engine, a business process execution engine, and a set of tools for managing business documents, along with the server.

Installing Commerce Gateway

There are multiple Commerce Gateway components:

  • Commerce Integration (also known as Commerce Gateway Request Client) is a subcomponent under Classic client in Setup. By default it is selected for install with the Classic client.

  • Commerce Gateway Request Server is a component that acts as a proxy server handling the requests from the Microsoft Dynamics NAV Classic client and passes them to BizTalk Server. To install Commerce Gateway Request Server, you must customize the list of components to install to include it. For more information, see How to: Choose Components to Install. Commerce Gateway Request Server is not included in any of the predefined Installation Options.

  • Commerce Gateway Broker is a component you must have if you have more than one NAV Application Server to handle Commerce Gateway communication. To install Commerce Gateway Broker, you must customize your list of components as described for the Commerce Gateway Request Server.

Commerce Gateway Documentation

For additional information about configuring Commerce Gateway, see w1w1NACG.pdf ("Installation & System Management:Commerce Gateway for Microsoft Dynamics NAV5.00"). To obtain this manual, go to Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download w1w1NACG.pdf.

Note Note

Use the PDF only for configuration information. The installation information in the manual is superseded by the "Installing Commerce Gateway" section, above.

See Also

Tasks

How to: Run Setup

Concepts

Commerce Gateway Requirements


Employee Portal

Employee Portal

Employee Portal is a Microsoft Dynamics NAV 2009 component that makes it easy for your employees to work with critical business information on your company intranet. Employees use Microsoft SharePoint Services—the Microsoft intranet standard—to access real-time business information directly from Microsoft Dynamics NAV 2009. With Employee Portal, your employees use a Web-based interface to see real-time business information updates.

Employee Portal Documentation

For additional information about Employee Portal, including information on installation and configuration, see w1w1ep.pdf ("Installation & System Management: Employee Portal for Microsoft Dynamics NAV"). To obtain this manual, go to Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download w1w1ep.pdf.

See Also

Tasks

How to: Run Setup


Business Notification

Business Notification

Business Notification is a component in Microsoft Dynamics NAV 2009 that can alert you to events that are important to your work, so you can manage your supply chain processes and other business areas with more impact.

Installing Business Notification

Business Notification contains the following components:

  • A Business Notification Client, which is installed by default as part of the Classic Server Components Option in Microsoft Dynamics NAV 2009 Setup.

  • A Business Notification Server, which you install with a separate Setup executable, located in the BNServer folder on the Microsoft Dynamics NAV 2009 DVD.

Business Notification Documentation

For additional information about Business Notification, see BusinessNotificationInstallationGuide.pdf. To obtain this manual, go to Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download BusinessNotificationInstallationGuide.pdf.

Note Note

Use the PDF only for configuration information. The installation information in the manual is superseded by the "Installing Business Notification" section, above.

See Also

Tasks

How to: Run Setup

Concepts

Classic Architecture


Microsoft Office Outlook Synchronization

Microsoft Office Outlook Synchronization

Use the Microsoft Office Outlook Integration component to synchronize data, such as to-dos, contacts, and tasks, between Microsoft Dynamics NAV 2009 and Outlook. You can use Outlook integration with either the Classic architecture (through Application Server) or with the RoleTailored architecture (through Web services).

Installing Microsoft Office Outlook Integration

You must install the Microsoft Office Outlook Add-In and other components before you set up Outlook integration. The following lists show which components and subcomponents that you must select in Microsoft Dynamics NAV Setup.

These sets of components do not correspond to any preconfigured installation options, so you must customize the list of components as you run Microsoft Dynamics NAV Setup. See How to: Choose Components to Install.

It is not necessary to install all listed components on a single computer. If you install different Microsoft Dynamics NAV components on different computers, then you must configure the components so that they can communicate. For more information, see Installation Walkthroughs.

If you want to configure Outlook integration to use Web services, then you must install the following components with Microsoft Dynamics NAV Setup.

Required components for configuring Outlook integration to use Web services

  • RoleTailored client

  • Microsoft Dynamics NAV Server

    • Microsoft Office Outlook Integration

  • Database components (installed on the computer running SQL Server)

    • Demo Database

  • Classic client

    • Microsoft Office Outlook Integration

  • Microsoft Office Outlook Add-In

If you want to configure Outlook integration to use Application Server, you must install the following components with Microsoft Dynamics NAV Setup

Required components for configuring Outlook integration to use Application Server

  • RoleTailored client

  • Database components (installed on the computer running SQL Server)

    • Demo Database

  • Classic client

    • Microsoft Office Outlook Integration

  • Application Server

    • Microsoft Office Outlook Integration

  • Microsoft Office Outlook Add-In

See Also

Tasks

Walkthrough: Setting Up Outlook Synchronization
Walkthrough: Synchronizing Information Between Outlook and Microsoft Dynamics NAV

Concepts

Classic Application Server

Other Resources

Working with Web Services


Installation Options

Installation Options

When you run Microsoft Dynamics NAV 2009 Setup, you are prompted to select from a list of predefined Installation Options, which are sets of one or more Microsoft Dynamics NAV components. The first Installation Option, the Demo Install option, appears on the first page that displays after accepting the license agreement in Setup. The remaining options are visible if you bypass the Demo and instead click Installation Options.

In This Section

Demo Install Option

Client Option

Server Option

Database Components Option

Classic Server Components Option

Developer Environment Option

Custom Components Option

Related Sections

Microsoft Dynamics NAV 2009 SP1 Requirements

Installing Microsoft Dynamics NAV 2009


Demo Install Option

Demo Install Option

The Demo Install option is visible on the first page after you accept the license agreement in Microsoft Dynamics NAV 2009 Setup. Setup then copies all three tiers of the RoleTailored Architecture to the local computer.

The Demo Install is intended for users who want to try out the features of Microsoft Dynamics NAV 2009. It is not intended as the foundation for an actual production environment.

Demo Install Option Notes

  • When you click Demo Install, Setup begins copying files. After this, you have no further interaction with Setup (except to click Close to exit Setup when it is finished copying files).

  • If Setup finds a copy of the Microsoft Dynamics NAV Demo database already on the destination computer, it fails. To resolve this problem, first delete the Demo database (as per the instructions in Modifying, Uninstalling, or Repairing), and then run Setup again.

  • Setup cannot install an .mdf file (the data file for a database) to the local computer if the destination folder or drive is compressed.

Installed Components

When you choose the Demo Install option, Setup installs the following components:

  • RoleTailored Client

  • Microsoft Dynamics NAV Server

  • Classic Client

  • Microsoft Office Outlook Add-in for Microsoft Dynamics NAV

  • SQL Server Express 2005, a smaller-scale version of SQL Server

  • A demo database with a demo license

See Also

Concepts

Demo Install Requirements
Properties of the Demo License


Properties of the Demo License

The demo license is automatically installed whenever you install a Microsoft Dynamics NAV 2009 client. The demo license works with the CRONUS demo database and has serial number 000 and includes granule 540. The license allows access to the entire base application and limited access to the development system.

Properties of the Demo License

When the demo license is installed, you can:

  • Start up to two simultaneous client sessions on any platform.

  • Create up to two companies.

  • Start up to two instances of Application Server.

  • Support an unlimited number of Web users.

  • Support an unlimited number of Employee Portal users.

  • Run with databases of up to 500 MB.

  • Use either Classic database server databases or SQL Server databases.

  • Run in any supported language.

  • Use all application functionality, including add-on products, local extensions and customizations in current and previous versions. This means that you can run, but not modify, all object types within the range 1 to 99,999,999.

  • Run and modify table 18, forms 21 and 22, report 101, and XMLports 99,008,503 and 99,008,510.

  • Run, modify and create fields 99,990 to 99,999, form 99,999, report 99,999, and MenuSuite 90.

Constraints of the Demo License

The demo license does not allow you to:

  • Import objects in text format, except for form and report ID 99,999.

  • Make more than 4,000 transactions in a database.

  • Enter dates in months other than November, December, January, and February.

A transaction is any action that requires interaction with the database, including posting an order, posting a worksheet, and synchronizing a record.

Country/Region Versions

When running a country/region version of Microsoft Dynamics NAV, the license must correspond with the country/region version that you have installed.

Any license can be available in different country/region versions. For example, Spanish license ES 4.00 SP2 completely installed can only run with a license serial numbers ES-ZA-xxx-xxxxx-x; Spanish license ES 4.00 SP2 database with a W1 4.00 SP2 completely installed can only run with a license serial numbers W1-ZA-xxx-xxxxx-x.

See Also

Tasks

Walkthrough: Installing the Demo Version

Concepts

Demo Install Option
Demo Install Requirements


Client Option

Client Option

The Client option is available on the Choose an installation option page in Microsoft Dynamics NAV 2009 Setup.

Installed Components

When you choose the Client option, Microsoft Dynamics NAV Setup installs the following component:

  • RoleTailored Client

    The RoleTailored client constitutes tier one in the Microsoft Dynamics NAV three-tier RoleTailored Architecture. (The NAV Server is tier two, and the Database Components, along with SQL Server or SQL Server Express, is tier three.)

See Also

Concepts

Client Option Requirements
Configuring the RoleTailored Client


Server Option

Server Option

The Server option is available on the Choose an installation option page in Microsoft Dynamics NAV 2009 Setup.

The single component in the Server option is the Microsoft Dynamics NAV Server, which constitutes the middle tier in the Microsoft Dynamics NAV three-tier RoleTailored Architecture. (The RoleTailored client is tier one, and the Database Components, along with SQL Server or SQL Server Express, is tier three.)

Note Note

Installing Microsoft Dynamics NAV Server on encrypted drives is not supported. You may run into issues if the server runs as a user that does not have access rights to the encrypted files.

Installed Components

When you choose the Server option, Microsoft Dynamics NAV Setup installs the following component:

  • Microsoft Dynamics NAV Server

See Also

Tasks

How to: Configure Windows Services

Concepts

Configuring Microsoft Dynamics NAV Server
Enhancing Microsoft Dynamics NAV Server Security


Database Components Option

Database Components Option

The Database Components option is available on the Choose an installation option page in Microsoft Dynamics NAV 2009 Setup.

The components in the Database Components option, along with Microsoft SQL Server, represent tier three in the Microsoft Dynamics NAV three-tier RoleTailored Architecture. (The RoleTailored client is tier one, and the NAV Server is tier two.)

Caution note Caution

Setup cannot install an .mdf file (the data file for a database) to the SQL Server database server if the destination folder or drive is compressed.

Installed Components

What Setup installs on the target computer with this option depends on whether it finds SQL Server already present on the computer:

  • If SQL Server is installed on the computer, Setup installs software that Microsoft Dynamics NAV requires for interacting with SQL Server.

  • If SQL Server is not installed on the computer, Setup installs Microsoft SQL Server Express 2005, along with software that Microsoft Dynamics NAV requires for interacting with SQL Server Express. SQL Server Express is best for prototyping and for demonstration purposes. Any production system you design around SQL Server Express would have to be very small—typically five users or less.

See Also

Concepts

Database Components Option Requirements
Installation Considerations for Microsoft SQL Server
Configuring Microsoft SQL Server
Configuring Database Components


Classic Server Components Option

Classic Server Components Option

The Classic Server Components option is available on the Choose an installation option page in Microsoft Dynamics NAV 2009 Setup.

The components in this option are updated versions of the components that comprised the previous version of Microsoft Dynamics NAV (version 5.0). These components, together with the Classic client, comprise the Classic Architecture in Microsoft Dynamics 2009.

Classic Server components are for organizations in the process of transitioning from the Classic architecture of version 5.0 to the new RoleTailored Architecture of Microsoft Dynamics NAV 2009.

Installed Components

When you choose the Classic Server Components option, Microsoft Dynamics NAV 2009 Setup installs the following components:

  • Classic Application Server

  • Classic Database Server

See Also

Concepts

Classic Server Components Option Requirements
Configuring Application Server
Configuring Classic Database Server


Developer Environment Option

Developer Environment Option

The Developer Environment option is available on the Choose an installation option page in Microsoft Dynamics NAV 2009 Setup.

The set of components installed with this option are those that a developer would typically use in designing Microsoft Dynamics NAV 2009 applications for a customer company.

Caution note Caution

The Developer Environment Option includes database components and a demo database. Setup cannot install an .mdf file (the data file for a database) if the destination folder or drive is compressed.

Installed Components

When you choose the Developer Environment option, Setup installs the following components:

  • RoleTailored Client

  • Classic Client

  • Microsoft Dynamics NAV Server

  • Database Components Option and a demo database

  • The Dynamics NAV 2009 Software Development Kit

This option installs all three tiers in the three-tiered RoleTailored Architecture, along with the Software Development Kit.

See Also

Concepts

Developer Environment Option Requirements


Custom Components Option

Custom Components Option

The Custom Components option is available on the Choose an installation option page in Microsoft Dynamics NAV 2009 Setup.

Installed Components

This option is unlike the other Installation Options available on the Choose an installation option page in Setup. It is not a selection from the complete list of available components created with a particular type of user or configuration, but rather the full list of individual Microsoft Dynamics NAV 2009 components, from which you can choose individual components to install (see How to: Choose Components to Install). This allows you to design your own Installation Option.

See Also

Tasks

How to: Preconfigure Components
How to: Create or Load a Setup Configuration File

Concepts

Requirements for Individual Components


Microsoft Dynamics NAV 2009 SP1 Requirements

Microsoft Dynamics NAV 2009 SP1 Requirements

Certain hardware and software must be present on a computer before you install Microsoft Dynamics NAV 2009 SP1. In this section, requirements are listed according to Installation Options, which are sets of one or more components that are installed together by Microsoft Dynamics NAV 2009 SP1 Setup.

Requirements are also provided for add-ins and supplemental tools and features that you can install with the Microsoft Dynamics NAV 2009 Setup program but which are not included in any of the installation options.

Note Note

If you have either SQL Server 2000 or Microsoft SQL Server Desktop Engine (MSDE) installed on a computer where you plan to install Microsoft Dynamics NAV 2009, then you must remove SQL Server before you begin installation. The presence of either of these older database products will cause a Setup error.

In This Section

Demo Install Requirements

Client Option Requirements

Server Option Requirements

Database Components Option Requirements

Classic Server Components Option Requirements

Developer Environment Option Requirements

Requirements for Developing Reports for the RoleTailored Client

Requirements for Individual Components

See Also

Other Resources

Installation Options


Demo Install Requirements

Demo Install Requirements

This section outlines the software and hardware that you need when you install the Demo Install Option.

Prerequisites

To install the Demo Install Option, you will need:

  • Microsoft Outlook 2003 or Microsoft Office Outlook 2007, which is required for the Microsoft Office Outlook Add-In for Microsoft Dynamics NAV.

  • Microsoft .NET Framework 3.5 SP1, which is installed automatically during Setup if it is not already installed.

If you do not already have one of the following versions of SQL Server, then Setup installs SQL Server Express 2005 automatically.

  • SQL Server 2008 Express, Workgroup, Standard, or Enterprise

  • SQL Server 2005 SP2 Express, Workgroup, Standard, or Enterprise

Software Requirements

The Microsoft Dynamics NAV Demo Option must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Microsoft Small Business Server 2008

  • Windows Essential Business Server 2008 Standard or Premium

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Microsoft Small Business Server 2003 R2 with SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Hardware Recommendations

Setup installs all Demo Install option components on one computer. This section outlines the minimum hardware that you need to run the Demo Install option.

Hard Disk Space

  • Minimum 1.5 GB

Memory

  • Minimum 1 GB

See Also

Concepts

Requirements for Individual Components
Properties of the Demo License


Client Option Requirements

Client Option Requirements

This section outlines the software and hardware that you need when you install the Client Option.

Prerequisites

To install the Client Option, you will need:

  • Microsoft .NET Framework 3.5 SP1, which is installed automatically during Setup if it is not already installed.

Software Requirements

The Microsoft Dynamics NAV Client Option must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Windows Server 2003 SP3

  • Windows XP Professional with SP3

Hardware Recommendations

This section outlines the minimum hardware that you need to run the Client Option.

Hard Disk Space

  • Minimum 30 MB

Memory

  • Minimum 1 GB

See Also

Concepts

Requirements for Individual Components


Server Option Requirements

Server Option Requirements

This section outlines the software and hardware that you need when you install the Server Option.

Prerequisites

To install the Server Option, you will need:

  • Microsoft .NET Framework 3.5, which is automatically installed during Setup if it is not already installed.

Note Note

Installing the Server Option on encrypted drives is not supported. You may run into issues if Microsoft Dynamics NAV Server runs as a user that does not have access rights to the encrypted files.

Software Requirements

The Microsoft Dynamics NAV Server Option must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Microsoft Small Business Server 2008

  • Windows Essential Business Server 2008 Standard or Premium

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Microsoft Small Business Server 2003 R2 with SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Hardware Recommendations

This section outlines the minimum hardware that you need to run the Server Option.

Hard Disk Space

  • Minimum 500 MB

Memory

  • Minimum 2 GB

See Also

Concepts

Requirements for Individual Components


Database Components Option Requirements

Database Components Option Requirements

This section outlines the software and hardware that you need when you install the Database Components Option.

Software Requirements

The Microsoft Dynamics NAV Database Components Option must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Hardware Recommendations

See hardware requirements for SQL Server 2008 or SQL Server 2005.

Requirements for Additional Software

If you do not already have one of the following versions of SQL Server, then Setup installs SQL Server Express 2005 automatically.

  • SQL Server 2008 Express, Workgroup, Standard, or Enterprise

  • SQL Server 2005 Express, Workgroup, Standard, or Enterprise with SP2

See Also

Concepts

Requirements for Individual Components
Configuring Database Components


Classic Server Components Option Requirements

Classic Server Components Option Requirements

This section outlines the software and hardware that you need when you install the Classic Server Components Option.

Software Requirements

The Microsoft Dynamics NAV Classic Server Components Option must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Microsoft Small Business Server 2008

  • Windows Essential Business Server 2008 Standard or Premium

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Microsoft Small Business Server 2003 R2 with SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Hardware Recommendations

This section outlines the minimum hardware that you need to run the Classic Server Option.

Hard Disk Space

  • Minimum 500 MB

  • Sufficient storage space for a database

  • Temporary space that is equivalent to the size of the largest primary index

Memory

  • Minimum 1 GB

CPU

  • Database Server and Application Server can only use one CPU per executable

    Note Note

    The maximum database size is 132 GB with the Classic database.

Network

If you run Application Server on a network, then you need:

  • WinSockets-compatible TCP/IP or NetBIOS-compatible LAN.

  • LAN network connection should be 100 megabits per second or better.

For more information, see:

  • Classic Database Server Requirements

  • Application Server Requirements

See Also

Concepts

Requirements for Individual Components


Developer Environment Option Requirements

Developer Environment Option Requirements

This section outlines the software and hardware that you need when you install the Developer Environment Option.

Prerequisites

To install the Developer Environment Option, you will need:

  • Microsoft .NET Framework 3.5 SP1, which is installed automatically during Setup if it is not already installed.

If you do not already have one of the following versions of SQL Server, then Setup installs SQL Server Express 2005 automatically.

  • SQL Server 2008 Express, Workgroup, Standard, or Enterprise

  • SQL Server 2005 Express, Workgroup, Standard, or Enterprise with SP2

Software Requirements

The Microsoft Dynamics NAV Developer Environment Option must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Microsoft Small Business Server 2008

  • Windows Essential Business Server 2008 Standard or Premium

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Microsoft Small Business Server 2003 R2 with SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Hardware Recommendations

This section outlines the minimum hardware that you need to run the Developer Environment Option.

Hard Disk Space

  • Minimum 3 GB

Memory

  • Minimum 1 GB

See Also

Concepts

Requirements for Individual Components


Requirements for Developing Reports for the RoleTailored Client

Requirements for Developing Reports for the RoleTailored Client
See Also

This topic describes the software that you need to create reports for the RoleTailored client.

Software Requirements

Creating a report for the RoleTailored client requires Object Designer, which is a tool that is built into the Classic client.

You must have one of the following Microsoft developer products:

  • Microsoft Visual Web Developer 2008 Express

    Note Note

    Microsoft Report Viewer Add-on for Visual Web Developer Express Edition 2008 is required. See the What entry in the NAV Reporting blog for an extra step that is required to make this work.

  • Visual Studio 2008 Express, Standard, or Professional with SP1

  • Visual Studio 2005 Standard or Professional with SP1

    Note Note

    The version of Visual Studio that is included in SQL Server 2005 is not supported. However, the version of Visual Studio 2008 that is included with Microsoft SQL Server 2008 is supported.

For the latest details on requirements for developing reports for the RoleTailored client, see the What entry on the NAV Reporting blog.

Note Note

Do not use Microsoft BizTalk Server as your XML editor for Visual Studio. Microsoft Dynamics NAV 2009 reports that are edited with BizTalk Server do not display in Visual Studio.

See Also

Concepts

Classic Client Requirements

Other Resources

Walkthrough: Designing a Customer List Report


Requirements for Individual Components

Requirements for Individual Components

The following set of topics is provided for users who may want to customize the list of components that make up an Installation Option, or to install individual components directly, without reference to any of the predefined Installation Options.

  • Classic Client Requirements

  • Classic Database Server Requirements

  • Application Server Requirements

  • Automated Data Capture System Requirements

  • Commerce Gateway Requirements

See Also

Tasks

How to: Run Setup
How to: Choose Components to Install
How to: Preconfigure Components


Classic Client Requirements

Classic Client Requirements

This section outlines the software and hardware that you need when you install the Classic client.

Prerequisites

To install the Classic client, you will need:

  • Microsoft .NET Framework 3.5 SP1, which is installed automatically during Setup if it is not already installed.

Software Requirements

The Classic client must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Hardware Requirements

This section outlines the minimum hardware that you need to run the Classic client.

Hard Disk Space

  • Minimum 250 MB of free space

Memory

  • Minimum 1 GB

Requirements for Additional Features and Options

You can customize the Classic client installation to include additional features and options. Some options impose additional software requirements.

  • If you install Business Notifications Manager with Microsoft Dynamics NAV Setup, then you must run Setup on a computer where SQL Server is already installed. Also, a server operating system is recommended, because it will have Microsoft Internet Information Services, which is also required. Additional requirements for Business Notifications Manager are:

    • 32-bit operating system: Business Notifications Manager is not supported on 64-bit operating systems.

    • SQLXML 3.0 SP2.

    • Microsoft SQL Server 2005 Notification Services. This is installed automatically with SQL Server 2005 but must be installed separately for SQL Server 2008.

  • Microsoft Office 2003 or the 2007 Microsoft Office system is required for e-mail logging, Outlook client integration, budget importing and exporting to and from Excel, and Office XML and SharePoint links.

    Note Note

    With the 2007 Microsoft Office system, you must install the Collaboration Data Object (CDO) to use e-mail logging.

See Also

Concepts

Classic Database Server Requirements
Requirements for Developing Reports for the RoleTailored Client
Application Server Requirements
Automated Data Capture System Requirements
Commerce Gateway Requirements


Classic Database Server Requirements

Classic Database Server Requirements

This section outlines the software and hardware that you need when you install Classic Database Server.

Software Requirements

Classic Database Server must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Microsoft Small Business Server 2008

  • Windows Essential Business Server 2008 Standard or Premium

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Microsoft Small Business Server 2003 R2 with SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Note Note

Hotcopy is a C/SIDE Database utility that can backup (file copy) Classic database .fdb files while these files are in use. Hotcopy can generate a notification e-mail message when the process has completed. This functionality requires Microsoft Office Outlook. Outlook Express is not supported.

Hardware Recommendations

This section outlines the minimum hardware that you need to run Classic Database Server.

Hard Disk Space

  • Minimum 500 MB

  • Sufficient storage space for a database

  • Temporary space that is equivalent to the size of the largest primary index

Memory

  • Minimum 1 GB

See Also

Concepts

Classic Client Requirements
Application Server Requirements
Automated Data Capture System Requirements
Commerce Gateway Requirements


Application Server Requirements

Application Server Requirements

This section outlines the software and hardware that you need when you install Application Server.

Software Requirements

Application Server must be installed on one of the following operating systems. Microsoft Dynamics NAV runs in 32-bit and 64-bit operating system editions. On 64-bit (x64) editions, Microsoft Dynamics NAV runs in WOW64 emulation mode.

  • Windows 7 Professional or Ultimate

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Hardware Recommendations

This section outlines the minimum hardware that you need to run Application Server.

Hard Disk Space

  • Minimum 250 MB of free space

Memory

  • Minimum 35 MB of free memory

Network

If you run Application Server on a network, then you need the following:

  • WinSockets compatible TCP/IP if you are using the TCP protocol with Microsoft Dynamics NAV Server.

See Also

Concepts

Classic Client Requirements
Classic Database Server Requirements
Automated Data Capture System Requirements
Commerce Gateway Requirements


Automated Data Capture System Requirements

Automated Data Capture System Requirements

This section outlines the software and hardware that you need when you install Automated Data Capture System.

Prerequisites

To install Automated Data Capture System, you will need:

  • Microsoft .NET Framework 3.5 SP1

  • MSXML version 6.0

Note Note

If these components are not already present, then they are are installed automatically when you install Microsoft Dynamics NAV Classic with Microsoft SQL Server.

Software Requirements

Automated Data Capture System must be installed on one of the following operating systems.

Note Note

Microsoft Dynamics NAV ADCS will not run on 64-bit operating system editions without some manual modifications.

  • Windows 7 Professional or Ultimate

  • Windows Server 2008

  • Windows Vista Business, Enterprise, or Ultimate with SP1 or SP2

  • Windows Server 2003 SP2

  • Windows XP Professional with SP3

Requirements for Additional Software

You need the following additional software when you choose to install Automated Data Capture System:

  • Microsoft Dynamics NAV Classic with Microsoft SQL Server or Microsoft Dynamics NAV Database Server.

  • Microsoft Dynamics NAV Application Server.

  • Telnet or Microsoft Windows HyperTerminal, which are available as standard Windows components.

  • VT100 Plug-in, which acts as a virtual telnet server and is required for each computer on which you want to install ADCS.

  • Loopback network adapter, which is an optional component if you want to use ADCS and do not have access to a network. For example, if you want to use ADCS for demonstration purposes.

    Note Note

    We recommend that you install the Application Server and the VT100 Plug-in on separate computers.

See Also

Concepts

Classic Client Requirements
Classic Database Server Requirements
Application Server Requirements
Commerce Gateway Requirements


Commerce Gateway Requirements

Commerce Gateway Requirements

This section outlines the software and hardware that you need when you install the Commerce Gateway Request Server and the Commerce Gateway client.

Prerequisites

To install the Commerce Gateway Request Server and client, you will need:

  • Microsoft .NET Framework 3.5 SP1, which is installed automatically during Setup if it is not already installed.

Software Requirements

Commerce Gateway Request Server and the Commerce Gateway client must be installed on a 32-bit edition of one of the following operating systems:

  • Windows Server 2008

  • Windows Server 2003 SP2

Hardware Recommendations

See the requirements for Microsoft BizTalk Server and Microsoft SQL Server.

Requirements for Additional Software

You need the following additional software when you install Commerce Gateway:

  • Microsoft BizTalk Server 2006 Developer or Standard

  • Microsoft BizTalk Server 2006 R2 Developer or Standard

  • SQL Server 2005 SP2 Express, Workgroup, Standard, or Enterprise (used by BizTalk Server 2006)

  • SQL Server 2008 Express, Workgroup, Standard, or Enterprise (used by BizTalk Server 2006 R2)

  • Microsoft Dynamics NAV Classic with Microsoft SQL Server or Microsoft Dynamics NAV Database Server

  • Application Server for Microsoft Dynamics NAV (You need Commerce Gateway Broker installed if you are running more than one Application Server.)

  • Microsoft XML Parser 3.0 SP2

  • Visual Studio 2005 or Visual Studio 2008 is required if you want to modify the BizTalk Server project files

    Note Note

    The Commerce Gateway Request Server must be installed on the same computer as BizTalk Server.

See Also

Concepts

Classic Client Requirements
Classic Database Server Requirements
Application Server Requirements
Automated Data Capture System Requirements


Installing Microsoft Dynamics NAV 2009

Installing Microsoft Dynamics NAV 2009

For Microsoft Dynamics NAV, Microsoft has completely redesigned the installation and configuration experience. Instead of running separate Setup programs for each component,.you can now install all Microsoft Dynamics NAV 2009 components from a single Setup program.

Note Note

Before installing Microsoft Dynamics NAV 2009 Service Pack 1 on a computer, you must uninstall any prior version of Microsoft Dynamics NAV 2009. You cannot install Microsoft Dynamics NAV 2009 Service Pack 1 on top of any prior version.

Key Concepts for Microsoft Dynamics NAV 2009 Setup

Before you install Microsoft Dynamics NAV, you should understand the following concepts about Setup.

Installation Options

Microsoft Dynamics NAV 2009 Setup offers six Installation Options, which each installs one or more components and is designed for a typical use or type of user.

Setup Configuration Files

You can customize the list of components to be installed and then preconfigure those components within Setup before creating a Setup configuration file. You can then use configuration file with other users. When those users run Setup with the configuration file, they get all customizations that you have built into the configuration file.

Required Security Configuration

After you install Microsoft Dynamics NAV, you must then set up security. For more information, see Overview: Setting Up Security. Without a security framework, even the user who has installed Microsoft Dynamics NAV software may not be able to run it until an administrator has created users and set up permissions.

Rapid Implementation Toolkit

For assistance with setting up companies in Microsoft Dynamics NAV, see the "Rapid Implementation Toolkit User Guide" (Dynamics NAV RIM Users Guide 2.0.pdf). You can find this guide on the Microsoft Dynamics NAV DVD, and, if you install the Documentation on your computer, in Microsoft Dynamics NAV\60\Application Guides\en-US directory.

In This Section

How to: Run Setup

Microsoft Software License Terms

Install Demo or Choose an Installation Option

How to: Choose Components to Install

How to: Preconfigure Components

How to: Create or Load a Setup Configuration File

Modifying, Uninstalling, or Repairing

Running Setup on the Command Line

How to: Install Classic Client for Administrative Tasks

How to: Activate the License File

Installation Considerations for Microsoft SQL Server

Installation Walkthroughs

Related Sections

Configuring Microsoft Dynamics NAV 2009

Overview: Setting Up Security


How to: Run Setup

How to: Run Setup

You can use Microsoft Dynamics NAV 2009 Setup to install software, create a customized list of components to install, or configure individual components. This topic describes a default software install with Setup, without any customization or configuration, and notes the opportunities available for more advanced uses of Setup.

Note Note

You must be an administrator on the computer where you run Setup.

Note Note

Before installing Microsoft Dynamics NAV 2009 Service Pack 1 on a computer, you must uninstall any prior version of Microsoft Dynamics NAV 2009. You cannot install Microsoft Dynamics NAV 2009 Service Pack 1 on top of any prior version.

Running Setup to Install an Installation Option

The simplest use of Setup is to install one of the predefined Installation Options.

To run Microsoft Dynamics NAV 2009 Setup

  1. Decide which of the Installation Options you want to install.

  2. Verify that the target computer meets the hardware and software requirements for the selected Installation Option. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

  3. Insert the Microsoft Dynamics NAV 2009 DVD.

    The Startup screen presents a set of options in sections entitled Prepare, Install, and Join the Community.

  4. Under Install, click Microsoft Dynamics NAV.

  5. Click Next to move past the Welcome screen.

  6. To indicate acceptance of the license terms, click I accept.

  7. Click either Install Demo or Choose an installation option.

    If you click Install Demo, Setup begins copying software and runs to completion without further input from you. For more information, see Demo Install Option. If you click Choose an installation option, you process to the Choose an installation option pane.

  8. On the Choose an installation option pane, click the larger text defining the name of an installation option to choose that option (for example, Client, Server, or Database Components).

    Optionally, you can click the word Customize, in smaller text, to modify the list of components before installing. For more information, see How to: Choose Components to Install.

    To install Microsoft Dynamics NAV 2009 software to a location other than the default location (C:\Program Files\Microsoft Dynamics NAV\60), click Customize and then click Destination folder on the Customize the installation pane.

  9. On the Specify Parameters page, you can choose to pre-configure any component shown with a black underscore.

    Each such component has an icon indicating one of three possible statuses. For more information about the meaning of these icons, refer to the information displayed at the bottom of the screen in Setup.

    For information about how to configure components, see How to: Preconfigure Components.

  10. After you configure components (or if you do not choose to configure components just now), click Install to begin copying software.

  11. When Setup is finished, click Close to exit Setup.

Canceling Setup

Setup does not provide a Cancel button on all panes, but you can cancel an installation from any pane by clicking the X in the upper-right corner. All Microsoft Dynamics NAV 2009 components are removed from the computer. The only software that Setup installs but cannot remove are:

  • Database files such as the Demo database.

  • Prerequisites for Microsoft Dynamics NAV 2009 components that Setup can install, such as the .NET Framework.

See Also

Tasks

How to: Choose Components to Install
How to: Preconfigure Components
How to: Create or Load a Setup Configuration File


Microsoft Software License Terms

Microsoft Software License Terms

The Microsoft Software License Terms page in Microsoft Dynamics NAV 2009 Setup defines the legal conditions under which you can use the Microsoft Dynamics NAV 2009 software. To continue with the installation, click I accept after reading the terms.

To print the software license terms, click Print.

See Also

Tasks

How to: Activate the License File


Install Demo or Choose an Installation Option

Install Demo or Choose an Installation Option

After you accept the software license terms and click Next, you come to the Microsoft Dynamics NAV 2009 Installer page. This page presents the following options:

  • Install Demo

    When you click this option, Setup immediately begins copying files. After this, you have no further interaction with Setup except to click Close to exit Setup after it is finished copying files.

    The Demo Install is intended for users who want to try out the features of Microsoft Dynamics NAV 2009. It is not intended as the foundation for a production environment.

  • Choose an Installation Option

    When you click this option, Setup moves to the Choose an Installation Option page, where you select from a set of predefined installation configurations. You can also modify any configurations on this page.

See Also

Tasks

How to: Run Setup

Concepts

Demo Install Option

Other Resources

Installation Options


How to: Choose Components to Install

How to: Choose Components to Install

As you run Microsoft Dynamics NAV Setup, you can install one of the predefined component collections, called Installation Options. If you need to modify the set of components included in an existing Installation Option, or create a new set of components, use the Customize the installation pane in Setup to choose components.

Choosing Components to Install

The following procedure describes how to get to that pane and what you can do when you get there.

To identify the components that you want to install

  1. In Setup, from the Choose an installation option pane, decide which Installation Option you want to customize, and then click Customize below the name of the Installation Option.

    This opens the Customize the installation pane with a selection of components already selected.

    An alternative is to click Custom Components on the Choose an installation option pane. This way you open the Customize the installation pane with no components already selected for install.

    Note Note

    To install Microsoft Dynamics NAV 2009 software to a location other than the default location (C:\Program Files\Microsoft Dynamics NAV\60), click Destination folder on the Customize the installation pane.

  2. Select the components that you want to install on the Customize the installation pane.

    Options are presented in a tree view.

    The tree has three levels of hierarchy:

    • The top level shows only a single node, Microsoft Dynamics NAV.

    • The second level shows additional nodes, each identifying a component (RoleTailored client, Server, etc.). Some second-level nodes have a plus sign on the left. Click the plus sign to reveal the third level of the hierarchy.

    • The third level shows subcomponents for the selected second-level component.

    Each node has one of three statuses, as indicated by its appearance.

    Component node Description
    White Node

    The component and all its subcomponents are selected for installation.
    Gray Node

    The component is selected for installation. Some or none (but not all) of the subcomponents are also selected. Only items on the top or second level can be gray (since only these nodes can have subcomponents).
    Red Node

    Neither the component nor any of its subcomponents are selected for installation.

  3. Click on a component to open a menu of options for that component (you must click within the box). The following options are available.

    Node option Description

    Run from My Computer

    Select this component for installation.

    Run all from my computer

    Select this component and all subcomponents for installation.

    Not available

    Cancel installation of this component and all subcomponents.

    For third-level nodes, and second-level nodes with no subcomponents, the only options are Run from My Computer and Not available.

  4. After you have selected the set of components and subcomponents that you want to install, click Next to proceed to the Specify parameters pane. Details on this process are in How to: Preconfigure Components.

See Also

Tasks

How to: Run Setup


How to: Preconfigure Components

How to: Preconfigure Components

Microsoft Dynamics NAV 2009 Setup supports pre-configuration of components in advance of installation, so that administrators can customize Microsoft Dynamics NAV 2009 components before deploying them to users.

After you have finished configuring components, you have two options:

  • Click Install to begin copying software.

    Caution note Caution

    In this case, you cannot reuse your configuration information. Setup does not prompt you to save your configuration settings.

  • Click Save the configuration in the Specify parameters pane.

For information about saving and loading Setup configuration files, see How to: Create or Load a Setup Configuration File.

Pre-Configuring Components

To associate configuration settings with a component before installing

  1. In Setup, from the Specify parameters pane, click any component displayed with an underscore.

    There are two visual indicators regarding the configurability of each component:

    • Underscore: Indicates that the component can be configured.

    • The icon to the left: Shows whether the component is ready to run and install (green check mark); in need of configuration before it can be used (green arrow with yellow alert), or in need of configuration before it can be installed (white arrow on blue background).

  2. In the Installation Parameters pane (which appears after you click a component with an underscore), enter values for all relevant parameters.

    For information about parameters for a configurable component, see one of the following:

    • Configuring the RoleTailored Client

    • Configuring Microsoft Dynamics NAV Server

    • Configuring Database Components

    • Configuring Application Server

    • Configuring Classic Database Server

    • Configuring Automated Data Capture System

  3. When you have finished configuring a component, click Apply to return to the Specify parameters pane in Setup.

See Also

Tasks

How to: Create or Load a Setup Configuration File


How to: Create or Load a Setup Configuration File

How to: Create or Load a Setup Configuration File

With Microsoft Dynamics NAV 2009 Setup, you can customize the list of components to install (see How to: Choose Components to Install) or configure settings for an individual components (see How to: Preconfigure Components).

After you have done such customization and configuration, you have the option to save this information to a configuration file which you can then re-use with Setup, either interactively, as you or another user runs Setup, or automatically, as part of a silent installation. For more information on silent installs, see Running Setup on the Command Line.

This topic describes how to save or load a configuration file.

Saving a Setup Configuration File

The option to create a new Setup configuration file, or save a modified setup configuration file, is on the Specify parameters pane in Microsoft Dynamics NAV 2009 Setup. You will always see this pane as you run Setup—unless you choose Install Demo, which bypasses all subsequent Setup panes.

To save a Setup configuration file

  1. In the Specify parameters pane, click Save the configuration.

  2. Type a file name for the configuration file. An .xml extension is added automatically.

  3. Click Save.

    You now return to the Specify parameters pane, where you can proceed with installing software. Or you can exit Setup at this point if your only objective was to create a Setup configuration file.

Loading a Setup Configuration File

The option to load a Setup configuration file is on the Choose an installation option pane in Microsoft Dynamics NAV 2009 Setup. This option is also available with a command-line install (see Running Setup on the Command Line).

Note Note

A Setup configuration file contains information about which components to install, and which settings to apply to each component. Therefore you should not customize the list of components or configure components in Setup before you load a Setup configuration file, since loading the configuration overwrites all prior customization and configuration.

To load a Setup configuration file in Setup

  1. In the Choose an installation option pane, click Load Configuration.

    This option is located under Custom Components, the third item in the second column.

  2. In the Open dialog, select or browse to the Setup configuration file that you want to open.

  3. Double-click to choose the file.

  4. Setup now shows the Customize the installation page. You can further modify the list of components to install, or click Next to proceed to the Specify parameters pane, where you can further configure settings for one or more components.

As noted, you should not make changes in Setup before loading a Setup configuration file. There is no problem with making changes in Setup after you load a Setup configuration file.

See Also

Concepts

Editing a Setup Configuration File


Editing a Setup Configuration File

Editing a Setup Configuration File

You create or load Setup configuration files using Microsoft Dynamics NAV 2009 Setup. You can directly edit these XML files.

Setup configuration files contain three types of settings.

Setting type Purpose

TargetPath

Specifies the name and location of the directory where Setup installs Microsoft Dynamics NAV 2009 software on the target computer.

There is only one instance of this setting per Setup configuration file.

ComponentID

These settings have two possible values: Local, to indicate that the component is included in the install, and Absent, to indicate that the component is not included. A Setup configuration file has one ComponentID setting for each item that Setup can install. You can change the value of a ComponentID setting, but you cannot add or remove any of these settings. If you do, you will not be able to use the resulting Setup configuration file.

ParameterID

These settings contain configuration information for components. As with ComponentIDs, you can modify the value of a ParameterID setting, but you cannot add or delete a ParameterID setting.

For information about values for pre-configuring Microsoft Dynamics NAV 2009 components using a Setup configuration file, see Configuring Microsoft Dynamics NAV 2009.

Tip: Microsoft Dynamics NAV 2009 Setup is primarily a tool for installing software, but you can also use it as an editor for creating and modifying Setup configuration files. When you want to edit a Setup configuration file, you have the following options:

  • You can edit the file using an XML editor.

  • You can load it into Setup, make the desired modifications, and then save it. You do not need to install any software during this process.

See Also

Tasks

How to: Choose Components to Install
How to: Preconfigure Components
How to: Create or Load a Setup Configuration File


Modifying, Uninstalling, or Repairing

Modifying, Uninstalling, or Repairing

If you run Microsoft Dynamics NAV 2009 Setup on a computer where any Microsoft Dynamics NAV 2009 components are already installed, you see the following options:

  • Add or Remove Components

    Select this option to navigate directly to the Customize the installation pane in Setup, where you can specify additional components to install on the local computer, or to remove from the local computer.

    When you select Add or Remove Components, Setup proceeds to the Customize the Installation pane.

    Click within the box of a component to open a menu of options for that component. The following options are available.

    Node option Behavior

    Run from My Computer

    Adds this component to the current installation.

    Run all from My Computer

    Adds this component and all subcomponents to the current installation.

    Not Available

    Removes this component and all subcomponents from the current installation.

    After you finish selecting components, click Next to proceed to the Specify parameters pane. See How to: Preconfigure Components for details.

  • Repair

    Select this option to repair any Microsoft Dynamics NAV 2009 components on the local computer that have become corrupted.

  • Uninstall

    Select this option to remove Microsoft Dynamics NAV 2009 components from the local computer.

    Note Note

    After you click Repair or Uninstall, Setup runs to completion with no further interaction. Your next option is to close Microsoft Dynamics NAV 2009 Setup.

Removing the Demo Database

Setup does not remove the demo database. After you use Setup to remove Microsoft Dynamics NAV software from your computer, you must manually remove the demo database.

With SQL Server

If you have SQL Server 2005 or SQL Server 2008, use SQL Server Management Studio to remove the Microsoft Dynamics NAV demo database, which is called Demo Database (6-0).

If you have installed SQL Server with the guidelines in Installation Considerations for Microsoft SQL Server, then SQL Server Management Studio is already installed on your computer. Otherwise, update your SQL Server installation to include either the Workstation components, Books Online, and development tools option for SQL Server 2005 or the Management Tools - Complete option for SQL Server 2008.

With SQL Server Express

If you did not have SQL Server on your computer when you installed the demo database, then Microsoft Dynamics NAV Setup installed SQL Server 2005 Express Edition to host the database. To remove the demo database, follow these steps:

  1. Download and install Microsoft SQL Server Management Studio Express from the Microsoft Download Center.

  2. Use SQL Server Management Studio Express to remove the Microsoft Dynamics NAV demo database, which is called Demo Database (6-0).

  3. Uninstall SQL Server 2005 Express Edition.

See Also

Tasks

How to: Choose Components to Install


Running Setup on the Command Line

Running Setup on the Command Line

You can run Microsoft Dynamics NAV 2009 Setup at a command prompt. On the Microsoft Dynamics NAV DVD, Setup.exe is in the root directory.

After installation, the typical location for Setup.exe on the target computer is:

CopyCode image Copy Code
C:\Program Files\Common Files\Microsoft Dynamics NAV\60\Setup

You can use the following options with Setup.exe.

Setup option | Description
/config <Setup config file> | Specifies path and file name information for a Microsoft Dynamics NAV 2009 Setup configuration file to load. This is the only required option.
/help | Displays Help about Setup.exe options.
/log <log path> | Specifies path and file name information for a Setup log file to be created by Setup. The file must not exist before you run Setup.
/quiet | Specifies that Setup will not display anything on the screen. All configuration information is taken from the specified configuration file.
/repair | Repairs the current installation of Microsoft Dynamics NAV 2009.
/uninstall | Removes the current installation of Microsoft Dynamics NAV 2009.

See Also

Tasks

How to: Create or Load a Setup Configuration File

Concepts

Editing a Setup Configuration File


How to: Install Classic Client for Administrative Tasks

How to: Install Classic Client for Administrative Tasks

Microsoft Dynamics NAV 2009 administrators need to use the Classic client, a component of the Classic Architecture, for administrative tasks such as activating license files or adding users. The Classic client is needed for administration even for installations based entirely on the RoleTailored Architecture.

You can install the Classic client as part of the Developer Environment Option, but if you do not want install all the other components that make up the Developer Environment, you can install the Classic client by itself.

Installing the Classic Client

To install the Classic client

  1. Insert the Microsoft Dynamics NAV 2009 DVD into the drive of your computer.

    The Startup pane presents a set of options in sections entitled Prepare, Install, and Join the Community.

  2. Under Install, click Microsoft Dynamics NAV.

    If you have already installed one or more Microsoft Dynamics NAV components on the computer, you will see the Maintenance pane instead of the Welcome pane. In this case, click Add or remove components and go to step 7.

  3. Click Next to move past the Welcome pane.

  4. To indicate acceptance of the license terms, click I accept.

  5. On the Microsoft Dynamics NAV 2009 Installer pane, click Choose an installation option.

  6. On the Choose an Installation Option pane, click Custom Components.

  7. On the Customize the Installation pane, click Classic client to display a menu of three options; from this menu, select Run from My Computer.

  8. Click Next to proceed to the Specify Parameters pane, where you see Classic client listed.

  9. Click Install.

  10. When Setup is finished, click Close.

See Also

Tasks

How to: Choose Components to Install
How to: Activate the License File
How to: Create Users


How to: Activate the License File

How to: Activate the License File

After an administrator or a Microsoft Certified Partner performs the initial install of Microsoft Dynamics NAV, the next step is to activate the license file that is supplied by Microsoft. You must upload the license file before you install any codeunits or deploy software to end users.

Note Note

Activating the license file is something you do once for each database installation, not once for each client installation.

Initially, Microsoft Dynamics NAV uses CRONUS.flf, which is the demonstration license file. All license files that are not demonstration license files have the name FIN.flf. The demonstration license file has been given a different name so that it cannot be mistakenly overwritten.

The steps for activating the license vary according to which database server you are using:

  • For SQL Server, you upload the license file to the database with the Classic client.

  • For Classic Database Server, you copy the license file to the Database Server.

Uploading the License File to the SQL Server Database

By default, the following procedure uploads the license for all Microsoft Dynamics NAV databases on the SQL Server instance. To upload a license for a specific database, in the Classic client, on the File menu, point to Database, and then click Alter. In the Alter Database window, click Integration, and then select Save license in database. For more information, click the Help button in the Alter Database window.

Note Note

To save the license file in the database, you must have the appropriate granule in your license.

To upload your license file

  1. Open the Classic client.

    Click Start, and then click Microsoft Dynamics NAV 2009 Classic with Microsoft SQL Server. If you have not already installed the Classic client, then see How to: Install Classic Client for Administrative Tasks.

    Note Note

    On a computer running Windows 7 or Windows Vista with User Access Control enabled, you must start the Classic client with administrator privileges. To do this, right-click the Classic client in the Start menu, and then click Run as administrator.

  2. On the Tools menu, click License Information.

  3. In the License Information window, click Upload.

    Note Note

    If you do not have a database connection, then the Upload button is not available.

  4. In the Upload License File window, browse to the folder where your Microsoft Dynamics NAV license file is located.

  5. Select the license file, and then click Open to upload it to the SQL Server database.

Copying the License File to Classic Database Server

This procedure assumes that you are using a database on the Database Server instead of running in single-user mode.

To copy your license file to the Classic Database Server

  1. Locate and copy your license file.

  2. On the computer where you have installed the Classic Database Server, navigate to the directory where the Classic Database Server executable, Server.exe, is located.

    The default location is Program Files\Microsoft Dynamics NAV\60\Database Server.

  3. Paste the license file in the server directory.

  4. Rename the file fin.flf if you have not already done so.

  5. Restart the Microsoft Dynamics NAV Database Server service.

    Note Note

    To save the license file in the database, you must have the Per Database License granule (2020) in your license.

See Also

Tasks

How to: Install Classic Client for Administrative Tasks
How to: Configure Windows Services

Concepts

Configuring Classic Database Server


Installation Considerations for Microsoft SQL Server

Installation Considerations for Microsoft SQL Server

This topic describes the requirements for installing and configuring Microsoft SQL Server to work with Microsoft Dynamics NAV 2009.

SQL Server Components to Install

Microsoft Dynamics NAV 2009 is compatible with SQL Server 2005 and SQL Server 2008.

SQL Server 2005 Components

If you are installing SQL Server 2005 to use with Microsoft Dynamics NAV, then install the following components:

  • SQL Server Database Services

  • Workstation components, Books Online, and development tools

Note Note

After you install SQL Server 2005, you must also install Service Pack 2.

SQL Server 2008 Components

If you are installing SQL Server 2008 to use with Microsoft Dynamics NAV, then install the following components:

  • Database Engine Services

  • Client Tools Connectivity

  • Management Tools - Complete

Setup Options for Microsoft SQL Server

When you are running Microsoft SQL Server Setup, you must provide additional information. Your responses can affect how you use SQL Server with Microsoft Dynamics NAV 2009.

Instances

Use the default instance and Instance ID on the Instance Configuration page when you install SQL Server. If you are using a non-default instance, then you must specify the instance when you install Microsoft Dynamics NAV Database Components. See Configuring Database Components.

Server Configuration

We recommend that you use a dedicated domain user account that you create specifically for the SQL Server service (MSSQLSVC) instead of a Local System account or the Network Service account.

Note Note

For more information on service security, see the Microsoft Dynamics NAV 2009 Security Hardening Guide.

Data Encryption Between Microsoft Dynamics NAV 2009 Server and SQL Server

When SQL Server and Microsoft Dynamics NAV Server are running on different computers, you can make this data channel more secure by encrypting the connection. For information on how to do this, see the topic “Encrypting Connections to SQL Server,” which is part of SQL Server 2008 Books Online on the MSDN library. You can link to the SQL Server 2005 version here and the SQL Server 2008 version here.

See Also

Concepts

Database Components Option
Configuring Microsoft SQL Server
Troubleshooting SQL Server Connection Problems


Installation Walkthroughs

Installation Walkthroughs

The walkthrough topics in this section present the various procedures that administrators or Microsoft Certified Partners would have to perform to successfully install the three tiers in the Microsoft Dynamics NAV 2009 RoleTailored Architecture.

The installations grow increasingly more complicated as different tiers (components) are installed on separate computers. The key distinction is not the actual number of computers used, but rather which components are installed on the same computer. Thus, the walkthrough "Installing the Three Tiers On Two Computers" applies to any configuration where NAV Server and SQL Server instances share a single computer, even when there might be five different computers hosting this combination of components.

The walkthrough, "Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer" describes a situation where you cannot use Setup to install the NAV Server software.

Note Note

For assistance with setting up companies after installing and configuring Microsoft Dynamics NAV software, see the "Rapid Implementation Toolkit User Guide" (Dynamics NAV RIM Users Guide 2.0.pdf). You can find this guide on the Microsoft Dynamics NAV DVD, and, if you install the Documentation on your computer, in Microsoft Dynamics NAV\60\Application Guides\en-US directory.

In This Section

Walkthrough: Installing the Demo Version

Walkthrough: Installing the Three Tiers On Two Computers

Walkthrough: Installing the Three Tiers on Three Computers

Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer

Walkthrough: Setting Up Outlook Synchronization

Walkthrough: Synchronizing Information Between Outlook and Microsoft Dynamics NAV

See Also

Tasks

How to: Run Setup
How to: Choose Components to Install
How to: Preconfigure Components


Walkthrough: Installing the Demo Version

Walkthrough: Installing the Demo Version

Install the Microsoft Dynamics NAV 2009 Demo to gain experience with product features. Do not use a Demo Install as the basis for an actual deployed production environment.

Note Note

Microsoft Dynamics NAV 2009 Setup always installs all components that comprise the Demo on a single computer.

Expand image Installed Components

The Demo version of Microsoft Dynamics NAV 2009 includes:

  • RoleTailored Client

  • Microsoft Dynamics NAV Server

  • Classic Client

  • Microsoft Office Outlook Add-in for Microsoft Dynamics NAV

  • SQL Server Express 2005, a smaller-scale version of SQL Server

  • The CRONUS International Ltd. demo database

  • a demo license

Expand image Recommendations and Constraints

Consider the following factors before you install and use the Microsoft Dynamics NAV 2009 Demo:

  • The Demo has not been tested to run side-by-side with previous versions of Microsoft Dynamics NAV. We recommend that you do not install the Demo on a computer that already has a previous version of Microsoft Dynamics NAV installed.

  • If you intend to use the Microsoft Outlook Add-In, install Outlook before installing the Demo.

  • You can install the Microsoft Dynamics NAV 2009 Demo on Windows Vista with User Account Control turned on or off. If User Access Control is turned on, right-click and choose Run as administrator to run the RoleTailored client.

Expand image Running Setup

To install the Demo

  1. Insert the Microsoft Dynamics NAV 2009 DVD.

    The Startup screen presents a set of options in sections entitled Prepare, Install, and Join the Community.

  2. Under Install, click Microsoft Dynamics NAV.

  3. Click Next to move past the Welcome screen.

  4. Click I accept to indicate acceptance of the license terms.

  5. Click Install Demo.

  6. When the installation is complete, click Close.

Expand image Next Steps

After installing the Demo, start the RoleTailored client from the Start menu. In Windows Vista, to run the RoleTailored client while User Account Control is turned on, click Start, and then click All Programs. Right-click the client, and, on the shortcut menu, click Run as administrator.

Note Note

The demo database is not uninstalled when you uninstall Microsoft Dynamics NAV 2009. You need to remove it manually. See the "Removing the Demo Database" section in the topic Modifying, Uninstalling, or Repairing.

Expand image See Also

Concepts

Demo Install Requirements
Properties of the Demo License


Walkthrough: Installing the Three Tiers On Two Computers

Walkthrough: Installing the Three Tiers On Two Computers

Microsoft Dynamics NAV 2009 introduces a new three-tier architecture that improves the security, scalability, and flexibility of Microsoft Dynamics NAV. For details, see RoleTailored Architecture. In this walkthrough, you install a new instance of Microsoft Dynamics NAV in a production environment on two computers.

Computer Description

NAVSERV

  • Server computer running Microsoft SQL Server and Microsoft Dynamics NAV Server.

  • This is the database and server tiers.

  • This computer runs Microsoft Windows Server 2003 or 2008.

NAVCLIENT

  • Client computer running the RoleTailored client.

  • This is the client tier.

  • This computer runs Windows Vista.

The key characteristic of this configuration is that the two server tiers—Microsoft Dynamics NAV Server and SQL Server—are on the same computer. If you install Microsoft Dynamics NAV Server and SQL Server on separate computers, you must set up delegation, to enable client to user the Microsoft Dynamics NAV Server service's credentials while interacting with a SQL Server database. See Walkthrough: Installing the Three Tiers on Three Computers.

Expand image About This Walkthrough

After completing this walkthrough, you will have a functioning three-tier installation on two computers. This installation uses the CRONUS International Ltd. demo database. This walkthrough assumes that you are running Windows Vista on the client computer, and Microsoft SQL Server 2008 and Windows Server 2008 on the server computer.

In this walkthrough, the Microsoft Dynamics NAV Server service uses the Network Service account. This requires less configuration work than a dedicated domain user account. However, the Network Service account is less secure because it is a shared account: users who have rights to this account have rights to all services run by this account. Running the Microsoft Dynamics NAV Server service under a dedicated domain user account is the more secure option, although it requires additional configuration by a domain administrator. For more information, see How To: Set Up Delegation.

This walkthrough illustrates the following tasks:

  • Installing the Microsoft Dynamics NAV database components.

  • Installing Microsoft Dynamics NAV Server.

  • Installing the RoleTailored client.

Prerequisites

To complete this walkthrough, you will need two computers configured as described in the introduction.

For information on installing Microsoft SQL Server, see Installation Considerations for Microsoft SQL Server.

For more information about configuring these computers according to Microsoft Dynamics NAV 2009 security best practices, see the Microsoft Dynamics NAV 2009 Security Hardening Guide.

Expand image Story

A consultant wants to install Microsoft Dynamics NAV 2009 to take advantage of the new three-tier architecture:

  1. He installs Microsoft Dynamics NAV database components and the sample database on the Windows Server 2008 computer where he has already installed Microsoft SQL Server (NAVSERV).

  2. He installs the middle-tier component, Microsoft Dynamics NAV Server, on the same computer.

  3. He installs the RoleTailored client on a separate Windows Vista computer (NAVCLIENT).

Expand image Installing the Microsoft Dynamics NAV Database Components

When you run Microsoft Dynamics NAV 2009 Setup you see a menu of Installation Options. One of those options, the Database Components option, installs software that configures Microsoft SQL Server to work with Microsoft Dynamics NAV 2009. This option also installs CRONUS International, Ltd., the Microsoft Dynamics NAV demo database.

To install the Microsoft Dynamics NAV Database Components and the demo database

  1. Insert the Microsoft Dynamics NAV 2009 DVD into the DVD drive of NAVSERV, the server computer where Microsoft SQL Server is already installed. The Startup screen presents a set of options grouped by category: Prepare, Install, and Join the community.

  2. Under Install, click Microsoft Dynamics NAV.

  3. On the Welcome screen, click Next.

  4. To accept the license terms, click I accept.

  5. On the Microsoft Dynamics NAV 2009 Installer page, click Choose an installation option.

  6. On the Choose an installation option page, click Database Components. The demo database is included as part of this option.

  7. On the Specify parameters page, click Install.

  8. After the installation is complete, click Close to exit Setup.

Expand image Installing Microsoft Dynamics NAV Server

The next step is to install the Microsoft Dynamics NAV Server service on the same computer.

Note Note

If you would rather configure Microsoft Dynamics NAV Server to use a domain user account, instead of the Network Service account, to access SQL Server, see the section on Configuring for a Domain User Account in Walkthrough: Installing the Three Tiers on Three Computers).

To install the NAV Server service

  1. Run Microsoft Dynamics NAV 2009 Setup again.

    You can either eject the DVD and reinsert it, or browse to Setup.exe on the DVD. When you run Setup, it presents the Maintenance page, because Microsoft Dynamics NAV software is already installed on the computer.

  2. On the Maintenance page, click Add or remove components.

  3. Click the Server option and select Run from My Computer.

  4. Click Next.

  5. On the Specify parameters page, click Install.

  6. After the installation is complete, click Close to exit Setup.

Expand image Installing the RoleTailored Client

The final task is to install the RoleTailored client to a workstation computer.

To install the RoleTailored client

  1. Insert the Microsoft Dynamics NAV DVD into the DVD drive of NAVCLIENT, the Microsoft Dynamics NAV client computer running Windows Vista.

  2. Under Install, click Microsoft Dynamics NAV.

  3. On the Welcome page, click Next.

  4. On the Microsoft Software License Terms page, review the software license, and then click I accept.

  5. On the Microsoft Dynamics NAV 2009 Installer page, click Choose an installation option.

  6. On the Choose an installation option page, click Client to install the RoleTailored client.

  7. On the Specify Parameters page, click RoleTailored client to configure the component.

  8. On the Installation Parameters pane, type the name of the Microsoft Dynamics NAV Server computer, which is NAVSERV, in the Server Name box.

    Note Note

    You can leave Server Port set to 7046.

  9. Click Apply.

  10. On the Specify parameters page, click Install to begin installing software.

  11. After the installation is complete, click Close to exit Setup.

Expand image Next Steps

Software installation is now complete. When you start the RoleTailored client it should connect to the Microsoft Dynamics NAV Server and inform you that you are connected to CRONUS International, Ltd. This the fictional company associated with the demo database.

The next steps are to upload your license, create users, and integrate them into the Microsoft Dynamics NAV security system. For information, see How to: Activate the License File and Security in the RoleTailored Environment.

Expand image See Also

Tasks

Walkthrough: Setting Up Outlook Synchronization
How to: Activate the License File
How to: Create Users

Concepts

RoleTailored Architecture
Configuring Microsoft SQL Server
Configuring Microsoft Dynamics NAV Server
Configuring the RoleTailored Client
Installation Considerations for Microsoft SQL Server
Security in the RoleTailored Environment


Walkthrough: Installing the Three Tiers on Three Computers

Walkthrough: Installing the Three Tiers on Three Computers

Microsoft Dynamics NAV 2009 introduces a new three-tier RoleTailored architecture that improves the security, scalability, and flexibility of Microsoft Dynamics NAV. For details, see RoleTailored Architecture. In this walkthrough, you will install the new architecture in a production environment on three computers:

Computer | Installed operating system and software | Tier
NAVSQL | Server computer running Windows Server 2008 or Windows Server 2003, and Microsoft SQL Server 2008 or SQL Server 2005 | Database tier
NAVSERV | Server computer running Windows Server 2008 or Windows Server 2003 and Microsoft Dynamics NAV Server | Server (middle) tier
NAVCLIENT | Client computer running Windows Vista | Client tier

The key characteristic of this walkthrough is that the client, Microsoft Dynamics NAV Server, and SQL Server are installed on separate computers. In a production environment, you may have multiple computers running SQL Server, multiple computers running Microsoft Dynamics NAV Server, and multiple computers running the RoleTailored client. But as long as you do not install multiple Microsoft Dynamics NAV tiers on the same computer, the procedures and issues presented in this walkthrough are relevant.

For information about the steps involved in installing both Microsoft Dynamics NAV Server and SQL Server on a single computer, see Walkthrough: Installing the Three Tiers On Two Computers.

Note Note

The content in this walkthrough only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Note Note

If after completing this walkthrough you find that your implementation is not working as expected, try using the Best Practices Analyzer for Microsoft Dynamics NAV 2009. Install this diagnostic tool on your Microsoft Dynamics NAV Server computer to identify configuration issues that might be preventing your three-tier deployment of Microsoft Dynamics NAV from working correctly. A PartnerSource login is required.

Expand image Domain User Account vs. Network Service

In this walkthrough, both the SQL Server service and the Microsoft Dynamics NAV Server service use a single domain user account. Using domain user accounts is not a requirement for three-tier-on-three-computer configurations. See the following note for the reason). It is also not a requirement that both the SQL Server service and the Microsoft Dynamics NAV Server service use the same domain user account. It is practical to use the same domain user account, and so that is what is described in this walkthrough.

In the three-tiers-on-two computers walkthrough (Walkthrough: Installing the Three Tiers On Two Computers), the SQL Server service uses a domain user account, but the Microsoft Dynamics NAV Server service uses the default account, which is the Network Service account.

Security note Security Note

You can use the Network Service account for the Microsoft Dynamics NAV Server service, which is how Setup installs Microsoft Dynamics NAV Server. This alternative is considered less secure because the Network Service account is a shared account that can be used by other unrelated network services. Any users who have rights to this account have rights to all services that are running on this account. Running the Microsoft Dynamics NAV Server service under a dedicated domain user account is more secure but does require additional work by a domain administrator. For more information, see Configuring for a Domain User Account.

Expand image About This Walkthrough

After completing this walkthrough, you will have a functioning three-tier installation on three computers. The installation uses the Microsoft Dynamics NAV Demo database, containing the CRONUS International Ltd. demo company.

This walkthrough illustrates the following tasks:

  • Installing the Microsoft Dynamics NAV database components.

  • Installing Microsoft Dynamics NAV Server.

  • Configuring for a domain user account.

  • Enabling the Object Change Listener.

  • Giving the Domain user account permissions for the server folder.

  • Installing the RoleTailored client.

  • Setting up delegation.

Prerequisites

To complete this walkthrough, you need three computers that are configured as described in the introduction.

For information on installing Microsoft SQL Server, see Installation Considerations for Microsoft SQL Server. (Specific SQL Server configuration issues are, however, covered at the appropriate location in the walkthrough.)

For more information about configuring these computers according to Microsoft Dynamics NAV 2009 security best practices, see the Microsoft Dynamics NAV 2009 Security Hardening Guide.

You must also have the setspn command-line tool installed on your server. In Windows Server 2008, the setspn tool is included if you have installed the Active Directory Domain Services server role. In Windows Server 2003, you must download the Windows Server 2003 Service Pack 2 32-bit Support Tools to get the setspn tool.

Expand image Story

A system implementer wants to install Microsoft Dynamics NAV 2009 to take advantage of the new three-tier architecture. She has already installed SQL Server on one server computer and will install the Microsoft Dynamics NAV database components and the sample database on that same server computer. She will then install Microsoft Dynamics NAV Server on a separate server computer. Finally, she will install the RoleTailored client on a Windows Vista client computer.

Expand image Installing the Microsoft Dynamics NAV Database Components

Run Microsoft Dynamics NAV 2009 Setup and select the Database Components option to configure SQL Server to work with Microsoft Dynamics NAV 2009. This option also installs the Microsoft Dynamics NAV demo database, which contains the CRONUS International Ltd. company.

To install the Microsoft Dynamics NAV database components and the demo database

  1. Insert the Microsoft Dynamics NAV 2009 DVD in the drive of NAVSQL, which is the server where SQL Server is already installed.

  2. On the startup page, under Install, click Microsoft Dynamics NAV.

  3. On the Welcome page, click Next.

  4. To accept the license terms, click I accept.

  5. On the Microsoft Dynamics NAV 2009 Installer page, click Choose an installation option.

  6. On the Choose an installation option page, click Database Components.

    The demo database is included as part of this option.

  7. On the Specify parameters page, click Install.

  8. After the installation is complete, click Close to exit Setup.

Expand image Installing Microsoft Dynamics NAV Server

The next step is to install Microsoft Dynamics NAV Server on NAVSERV, which is the second server computer. This is a different server computer from the one where you installed SQL Server and the Microsoft Dynamics NAV database components.

To install Microsoft Dynamics NAV Server

  1. Insert the Microsoft Dynamics NAV DVD into the drive of NAVSERV.

  2. On the startup page, under Install, click Microsoft Dynamics NAV.

  3. On the Welcome page, click Next.

  4. To accept the license terms, click I accept.

  5. On the Microsoft Dynamics NAV 2009 Installer page, click Choose an installation option.

  6. On the Choose an installation option page, click Server.

  7. On the Specify parameters page, click Server to open the Installation Parameters pane.

  8. In the SQL Server field, type NAVSQL, which is the name of the computer running SQL Server.

  9. In the SQL Database field, type Demo Database NAV (6-0).

    This is the Microsoft Dynamics NAV demo database, which contains the CRONUS International, Ltd., demonstration company.

  10. Click Apply to save the Microsoft Dynamics NAV Server settings.

  11. Click Install to start installing software.

  12. After the installation is complete, click Close to exit Setup.

Expand image Configuring for a Domain User Account

The procedures in this section are necessary only when the logon for Microsoft Dynamics NAV Server is a domain user account instead of the Network Service account. You can only perform these actions if you have domain administrator privileges.

The steps that are involved in creating a domain user account by using the Active Directory Users and Computers utility (dsa.msc) are part of the Active Directory documentation, which is included in the Windows Server documentation.

Raising the Domain Functional Level

After you create the domain user account, you must verify that the Domain Functional Level or your domain is at least Windows Server 2003 level.

Caution note Caution

Do not raise the domain functional level if you have or will have any Microsoft Windows NT 4.0 or earlier domain controllers. As soon as the domain functional level is raised to Windows 2000 native or Windows Server 2003, it cannot be changed back to a Windows 2000 mixed domain.

To determine if the functional level of your domain is at least Windows Server 2003 level and to raise it if it is not, follow these steps:

  1. Choose Run from the Start menu in Windows, type dsa.msc, and then press ENTER.

    This opens the Active Directory Users and Computers utility. This utility is part of Windows Server 2003 or Windows Server 2008.

  2. Right-click the domain where Microsoft Dynamics NAV is installed, and then click Raise Domain Functional Level.

    If the level is at least Windows Server 2003, then you can close the utility. Otherwise, continue to the final step.

  3. Under Select an available domain functional level, click Windows Server 2003, and then click Raise.

Change the Logon Account for the Microsoft Dynamics NAV Server Service and the SQL Server Service

Change the logon account for the Microsoft Dynamics NAV Server service and the SQL Server service to use your domain user account. For information about how to configure Windows Services, see How to: Configure Windows Services.

Note Note

As described in How to: Configure Windows Services, you should actually use different tools to configure the respective services: use the Service tool from Windows Control Panel for the Microsoft Dynamics NAV Server service, and use the SQL Server Configuration Manager tool for the SQL Server service. This assures that that permissions required for the SQL Server service account are granted.

Expand image Enabling the Object Change Listener

The Object Change Listener (OCL) component of Microsoft Dynamics NAV Server monitors the database for changes that are made to application objects, such as adding a new field to a page. If OCL cannot start because of permissions errors, then you cannot connect clients to the server. When you try to start the RoleTailored client, you see the following message:

Cannot connect the Change Listener to SQL Server.

For more information, see Enabling the Object Change Listener.

To enable and assign minimum permissions for the Object Change Listener

  1. Open SQL Server Management Studio, and then connect to your SQL Server instance.

  2. On the File menu, point to New, and then click Query with Current Connection.

  3. Type the following SQL statements.

    CopyCode image Copy Code
    USE MASTER
CREATE LOGIN [ReplaceWithNAVServerAccount] FROM WINDOWS;
GO

  4. Highlight the lines that you typed, and then on the Query menu, click Execute.

  5. Type these lines after the existing lines.

    CopyCode image Copy Code
    USE [ReplaceWithYourDatabaseName]
CREATE USER [ReplaceWithNAVServerAccount] FOR LOGIN [ReplaceWithNAVServerAccount];

  6. Highlight the lines that you just typed, and then on the Query menu, click Execute.

  7. Type these lines after the existing lines.

    CopyCode image Copy Code
    CREATE SCHEMA [$ndo$navlistener] AUTHORIZATION [ReplaceWithNAVServerAccount];
GO

  8. Highlight the lines that you just typed, and then on the Query menu, click Execute.

    You may see an error stating that the schema in question already exists. You can ignore this error.

  9. Type these lines after the existing lines.

    CopyCode image Copy Code
    ALTER USER [ReplaceWithNAVServerAccount] WITH DEFAULT_SCHEMA = [$ndo$navlistener];
GRANT SELECT ON [Object Tracking] TO [ReplaceWithNAVServerAccount];
GO

  10. Highlight the lines that you just typed, and then on the Query menu, click Execute.

    Note Note

    The Object Tracking table name may be in a different language than English. If it is, then replace "Object Tracking" with the actual table name from your database.

  11. Save your query to keep a record of these actions.

    You can use these commands again when you create a new database or change the account that you use to run Microsoft Dynamics NAV Server.

Expand image Giving the Domain User Account Permissions for the Server Folder

The next step is to give the domain user account full permissions for the Microsoft Dynamics NAV Server folder on the computer where you installed Microsoft Dynamics NAV Server.

To grant the domain user account permissions on the Microsoft Dynamics NAV Server folder

  1. In Windows Explorer, navigate to the Microsoft Dynamics NAV Server folder on the computer where you have installed Microsoft Dynamics NAV Server. On Windows Server 2003, the default location is:

    Documents and Settings\All Users\Application Data\Microsoft\Microsoft Dynamics NAV\60

    On Windows Server 2008 or Windows Vista, the default location is:

    ProgramData\Microsoft\Microsoft Dynamics NAV\60\

  2. Right-click the Service folder, and then click Properties to open the Service Properties dialog box.

  3. Click the Security tab.

  4. Select the domain user account from the list in the top half of the dialog box, and then, in the Permissions for section in the bottom half, select Allow next to the Full Control permission.

    This grants the domain user account full control of the folder.

  5. Select the NETWORK SERVICE account in the top half, and then clear the Allow field next to the Full control permission in the bottom half.

    This revokes permissions on the folder for the Network Service account. No account other than your domain user account should have access to the server folder.

  6. Click OK to close the Service Properties dialog box.

Expand image Installing the RoleTailored Client

The third and final tier is the client tier. The first task is to install the RoleTailored client to a workstation computer.

To install the RoleTailored client

  1. Insert the Microsoft Dynamics NAV DVD into the drive of NAVCLIENT, which is your Microsoft Dynamics NAV client computer.

  2. On the startup page, under Install, click Microsoft Dynamics NAV.

  3. On the Welcome page, click Next.

  4. To accept the license terms, click I accept.

  5. On the Microsoft Dynamics NAV 2009 Installer page, click Choose an installation option.

  6. On the Choose an installation option page, click Client to install the RoleTailored client.

  7. On the Specify parameters page, click RoleTailored client to configure the component.

  8. In the Installation Parameters dialog box, type NAVSERV, which is the name of the computer running Microsoft Dynamics NAV Server, in the Server Name field.

    You should fully qualify the domain name in this field (in the form YourServer.YourDomain.YourCompany.com).

  9. Click Apply, and then click Apply on the Specify parameters page to start installing software.

  10. After installation is complete, click Close to exit.

Expand image Setting Up Delegation

When the RoleTailored client, Microsoft Dynamics NAV Server, and SQL Server are installed on separate computers, the client interacts with the database through an intermediate computer, which is running Microsoft Dynamics NAV Server. The server is performing actions on the client's behalf. This process is known as impersonation.

Delegation is when a front-end service forwards the client’s request to a back-end service so that the back-end service can also impersonate the client. Complete the procedures in this section to set up delegation on your Microsoft Dynamics NAV installation. For more information on delegation, see How To: Set Up Delegation.

Create Service Principal Names

The first step in setting up delegation is to create service principal names (SPN). To make delegation more secure, Active Directory uses Kerberos to authenticate services. An SPN is the name by which a client uniquely identifies an instance of a service, using the account under which the service runs. You must create one SPN for the Microsoft Dynamics NAV Server service and one SPN for the SQL Server service to make delegation work.

To create service principal names

  1. Open an elevated command prompt. To do this, click Start, and then in the search window, type Command Prompt. Right-click Command Prompt, and then click Run as administrator.

  2. At the command prompt, create an SPN for the Microsoft Dynamics NAV Server service. The syntax is:

    CopyCode image Copy Code
    setspn -A InstanceName/FullyQualifiedDomainNameOfServer:Port Domain\User

    Using NAVSERV, which is the computer running Microsoft Dynamics NAV Server, and DynamicsNAV, which is the default instance name for Microsoft Dynamics NAV Server, the actual command has the following format:

    CopyCode image Copy Code
    setspn -A DynamicsNAV/NAVSERV.yourDomain.yourCompany.com:7046 yourDomain\yourUser

    Replace "yourDomain," "yourCompany," and "yourUser" with the appropriate values.

  3. Create an SPN for the SQL Server service. This service runs on the NAVSQL computer with a default instance name of MSSQLSvc. Type the following command:

    CopyCode image Copy Code
    setspn -A MSSQLSvc/NAVSQL.yourDomain.yourCompany.com:1433 yourDomain\yourUser

    Again, replace "yourDomain," "yourCompany," and "yourUser" with the appropriate values.

Delegating Access to the SQL Server Service

Configuring delegation means explicitly configuring the Microsoft Dynamics NAV Server service on NAVSERV to delegate its access to the database server on behalf of the RoleTailored client. To make the access more secure, you specify delegation to a specific service on a specific server. In this walkthrough, you specify delegation on the SQL Server database service (MSSQLSERVER). This is known as constrained delegation.

You must run the following procedure on a computer where the Active Directory Users and Computers utility (dsa.msc) is available.

To delegate access to the SQL Server service

  1. Click Start, and then click Run.

  2. In the Open field, type dsa.msc.

    This opens the Active Directory Users and Computers utility.

  3. Right-click the node for the domain where you have installed Microsoft Dynamics NAV, and then click Find.

  4. In the Find Users, Contacts, and Group dialog box, type the name of the domain user in the Name field, and then press ENTER.

  5. In the Search results area, right-click the domain user, and then click Properties.

  6. On the Delegation tab, click Trust this user for delegation to specified services only, and then click Use Kerberos only.

    There is also the option to not restrict authorization to Kerberos, although the environment is not as secure when you are less restrictive. Your decision must be reflected in the value that you assign to the AllowNtlm setting in the RoleTailored client configuration file (ClientUserSettings.config). For details, see Configuring the RoleTailored Client.

  7. Click Add to open the Add Services dialog box.

  8. Click Users or Computers, and then specify the domain user.

  9. In the list of services for the domain user, click MSSQLSvc, which is the SQL Server service.

  10. Click OK to close the Add Services dialog box. Continue clicking OK to close all open dialog boxes.

Delegation from the domain user to the SQL Server service on a separate computer is now enabled.

Expand image Establishing a Connection

The configuration is now complete. You should be able to start the RoleTailored client and see it connect to the CRONUS International Ltd. demo database immediately.

If you are cannot connect the RoleTailored client to Microsoft Dynamics NAV Server after completing this procedure, the problem may be that Microsoft Dynamics NAV Server is not able to connect to SQL Server. For more information, see Troubleshooting SQL Server Connection Problems.

Expand image Next Steps

You have now installed all Microsoft Dynamics NAV software. When you start the RoleTailored client, it connects to Microsoft Dynamics NAV Server and to CRONUS International Ltd., which is the fictional company that is associated with the demo database.

The next steps are to upload your license, create users, and integrate them into the Microsoft Dynamics NAV security system. For more information, see How to: Activate the License File and Security in the RoleTailored Environment.

Expand image See Also

Tasks

How to: Activate the License File
How to: Create Users
How To: Set Up Delegation

Concepts

RoleTailored Architecture
Configuring Microsoft SQL Server
Configuring Microsoft Dynamics NAV Server
Configuring the RoleTailored Client


How to: Configure Web Services with Delegation

How to: Configure Web Services with Delegation

Note Note

This topic requires that you have successfully completed the procedures in the Walkthrough: Installing the Three Tiers on Three Computers topic, which describes how to install and configure Microsoft Dynamics NAV 2009 in a production environment on three computers.

This topic extends installing three tiers on three computers by adding a Web services client. This client communicates with the database through the Microsoft Dynamics NAV Business Web Services service, which is a Windows service that is automatically installed when you install Microsoft Dynamics NAV Server. After installing Microsoft Dynamics NAV Server, you can see the Microsoft Dynamics NAV Business Web Services service listed just above Microsoft Dynamics NAV Server in the Windows services tool:

Services associated with Dynamics NAV Server

These two services use the same process in Windows and must always run using the same account. Because you have already configured Microsoft Dynamics NAV Server to log on using a dedicated domain user account, you must configure the Microsoft Dynamics NAV Business Web Services service to log on with the same dedicated domain user account. For more information, see How to: Configure Windows Services.

Note Note

You can create multiple Microsoft Dynamics NAV Web services server on a single computer. For details, see "Creating a Second Web Services Server on a Single Computer" in Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer. Also see Creating a web service manually, the importance of the name you give it, and a few small things to remember on the Microsoft Dynamics NAV Team Blog.

Configuring Web Services for Delegation

After you start the Microsoft Dynamics NAV Business Web Services service, you will create two service principal names (SPN) for the service. To make delegation more secure, Active Directory uses Kerberos to authenticate services. An SPN is the name by which a client uniquely identifies an instance of a service, using the account under which the service runs. You must create two SPNs for the Microsoft Dynamics NAV Business Web Services service:

  • One for URLs that use the fully qualified domain name of the server.

  • One for URLs that use the Net BIOSname.

Note Note

This procedure uses the httpcfg tool for configuring the HTTP server. When you install Microsoft Dynamics NAV Server, Setup puts a copy of httpcfg.exe in the Microsoft Dynamics NAV Server directory. By default, this directory is C:\Program Files\Microsoft Dynamics NAV\60\Service.

To configure Microsoft Dynamics NAV Web services for delegation

  1. In Control Panel, click Administrative Tools, and then click Services.

  2. In the list of services, scroll down to Microsoft Dynamics NAV Business Web Services.

  3. Double-click to open the Properties dialog box for this service, and then click Start.

    Note Note

    The Microsoft Dynamics NAV Business Web Services service is not configured to start automatically when you start the computer. If you want this service to start automatically, in the Properties dialog box for this service, on the General tab, select Automatic as the value for Startup type.

  4. Open an elevated command prompt. Click Start, and in the search window, type Command Prompt.

  5. Right-click Command Prompt, and then click Run as administrator.

  6. At the command prompt, use the setspn command to create two SPNs for the Microsoft Dynamics NAV Business Web Services service. The syntax is:

    CopyCode image Copy Code
    setspn -A http/NameOfServer Domain\User

    The http/ indicates that the SPN is for the Web services server.

    1. The first setspn command, using the fully qualified domain name of the server, has this format:

      CopyCode image Copy Code
      setspn -A http/NAVSERV.yourDomain.yourCompany.com yourDomain\yourUser

      Replace NAVSERV with the name of the computer running Microsoft Dynamics NAV Server, and replace yourCompany, yourDomain, and yourUser with the actual company, domain, and user account names.

    2. The second setspn command excludes the company and domain from the server address:

      CopyCode image Copy Code
      setspn -A http/NAVSERV yourDomain\yourUser

      This SPN accommodates Web services clients that connect using the NetBIOS name of the server.

  7. Use httpcfg to register the access control list (ACL) that is associated with the Web service URL for the domain user. An ACL is part of the Windows security infrastructure. For details, see Access Control Lists.

    CopyCode image Copy Code
    httpcfg http delete urlacl –u http://+:7047/DynamicsNAV/
httpcfg set urlacl -u http://+:7047/DynamicsNAV/ -a D:^(A;^;GX^;^;^;<security identifier>)

    Replace <security identifier> with the actual security-identifier attribute (SID) for the account. A security identifier is a unique value of variable length used to identify a user or group account. For details, see Security Identifiers.

    Note Note

    If you have previously configured Microsoft Dynamics NAV Web services to use SSL, use "https" in the two httpcfg commands instead of "http". For more information, see Walkthrough: Configuring Web Services to Use SSL.

  8. Close the command prompt.

    Your Web service clients should now be able to connect with Web services on the computer running Microsoft Dynamics NAV Server to your SQL Server database on a separate computer.

See Also

Other Resources

Working with Web Services


Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer

Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer
See Also
CollapseAll image

In Microsoft Dynamics NAV 2009, to connect to more than one database from the same computer running Microsoft Dynamics NAV Server, you must create two distinct instances of Microsoft Dynamics NAV Server. You cannot create the second instance using Microsoft Dynamics NAV Setup.

The computer running Microsoft Dynamics NAV Server is the middle tier between the client and the database and runs as a service within the Windows Communication Framework. Before you can connect the RoleTailored client to a second database through a single Microsoft Dynamics NAV Server computer, you must create a second Microsoft Dynamics NAV Server service on that server computer.

Expand image About This Walkthrough

This walkthrough is a step-by-step guide to installing two instances of Microsoft Dynamics NAV Server on a single server computer. This walkthrough illustrates the following tasks:

  • Creating the second Microsoft Dynamics NAV Server service with the sc utility.

  • Configuring the second service.

  • Connecting to either Microsoft Dynamics NAV Server service with the RoleTailored client.

  • Testing the second service.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft SQL Server 2008 or SQL Server 2005 on a computer running Windows Server 2008 or Windows Server 2003.

  • Microsoft Dynamics NAV 2009 Database Components and the first Microsoft Dynamics NAV Server on the same server computer.

  • RoleTailored client on a separate computer to test the installation.

Expand image Story

  • Simon, the IT professional at CRONUS International, is developing new page objects for a customer but does not want to deploy the new pages directly to a production environment. He decides to create one database for developing new page objects and another database for testing them with the RoleTailored client. He wants to host both databases on the same server computer.

  • Simon knows that he must install multiple computers running Microsoft Dynamics NAV Server to achieve this result. Simon also knows that he can only create the second service using the service create (sc) utility at the command prompt.

Expand image Creating a Second Service

Simon creates a second service by running the sc command at the command prompt. When he runs this command, he creates a second service that appears in the Services snap-in in Control Panel.

To create a second service

  1. In Control Panel, click Administrative Tools, and then click Services to open the Services snap-in.

  2. In the list of services, right-click Microsoft Dynamics NAV Server, and then click Stop.

  3. Navigate to the Microsoft Dynamics NAV Service directory. This directory is typically located at C:\Program Files\Microsoft Dynamics NAV\60\.

  4. Copy the service directory and paste it into the same directory. Rename the copy from Copy of Service to Service2.

  5. At the command prompt, type the sc command to create a new service. Copy the following command and paste it at the command prompt. Replace <computername> with the actual computer name.

    CopyCode image Copy Code
    sc \\<computername> create MicrosoftDynamicsNAVServer$NAV2 binpath= "C:\Program Files\Microsoft Dynamics NAV\60\Service2\Microsoft.Dynamics.Nav.Server.exe $NAV2" DisplayName= "Microsoft Dynamics NAV Server Instance 2" start= auto type= own depend= NetTcpPortSharing
    Note Note

    You can also specify a login account for the service as part of the sc command using the obj parameter, such as:

    CopyCode image Copy Code
    obj= "NT Authority\NetworkService"

  6. If the command succeeds, then you receive the following message:

    [SC] CreateService SUCCESS

    In the Services snap-in, you see your second service, Microsoft Dynamics NAV Server Instance 2, in the list.

  7. Double-click the new service to open a Properties dialog box for the new service, and then click the Log On tab.

    The default setting is for the service to log on with the Local System Account. Setup configures the original Microsoft Dynamics NAV Server service to use the Network Service account. This walkthrough also uses the Network Service account for the second service. For improved security, you should use a dedicated domain user account. For information on how to configure a Microsoft Dynamics NAV Server service to use a domain user account, see Walkthrough: Installing the Three Tiers on Three Computers.

  8. Click This account on the Log On tab.

  9. Type NT Authority\NetworkService in the first text box.

  10. Clear the entries in the Password and Confirm password fields.

  11. Click OK to exit the Properties dialog box for the new service.

  12. Right-click Microsoft Dynamics NAV Server Instance 2, and then click Start to verify that the service is configured correctly.

  13. Right-click Microsoft Dynamics NAV Server Instance 2 again, and then click Stop.

Expand image Configuring a Second Service

Before Simon can start to use the second service, he must create a name for the new server instance. He must also activate port sharing so that multiple clients can share the same port number.

To create a name for the server instance

  1. Use Notepad or another text editor and open the CustomSettings.config file in the Service2 directory. The default path for this file is C:\Program Files\Microsoft Dynamics NAV\60\Service2\Custom.Settings.config.

  2. Locate the following line:

    CopyCode image Copy Code
    <add key="ServerInstance" value="DynamicsNAV" />

    Replace DynamicsNAV with DynamicsNAV2, which is the name for your new server instance.

  3. Save your changes, and then close the editor.

To activate port sharing

  1. Return to the Services snap-in.

  2. Right-click Net.Tcp Port Sharing Service, and then click Properties.

  3. On the General tab, set Startup type to Manual.

  4. Click OK to close the Properties window.

  5. Right-click Net.Tcp Port Sharing, and then click Start.

    You have now activated port sharing over the TCP/IP protocol.

Note Note

You can also specify a separate port number for each Microsoft Dynamics NAV Server service. You then do not need to implement TCP port sharing.

It is not possible to run the Microsoft Dynamics NAV Server service with port sharing if the service is running on a domain user account. If you need to run two Microsoft Dynamics NAV Server services on the same computer, then you must run the services with the Network Service account.

Expand image Recreate the Original Microsoft Dynamics NAV Server Service with TCP Port Sharing

To reconfigure the original Microsoft Dynamics NAV Server service to use TCP port sharing, you must use the sc command to delete the service and then use it again to recreate the service with the proper configuration.

To recreate the original Microsoft Dynamics NAV Server service

  1. At the command prompt, type the following command to delete the Microsoft Dynamics NAV Server service:

    CopyCode image Copy Code
    sc delete MicrosoftDynamicsNavServer
    Note Note

    If you attempt to delete a service while it is running, then the service is marked for deletion but is not deleted until you restart the computer.

  2. At the command prompt, recreate the original Microsoft Dynamics NAV Server service with the option for TCP port sharing:

    CopyCode image Copy Code
    sc \\<computername> create MicrosoftDynamicsNAVServer binpath= "C:\Program Files\Microsoft Dynamics NAV\60\Service\Microsoft.Dynamics.Nav.Server.exe" DisplayName= "Microsoft Dynamics NAV Server" start= auto type= own depend= NetTcpPortSharing

  3. If the service has been created successfully, then you receive the following message:

    CopyCode image Copy Code
    [SC] CreateService SUCCESS

  4. If the Services snap-in is still open, then close it and reopen it to update the information in the snap-in. Otherwise, reopen the Services snap-in.

  5. Double-click Microsoft Dynamics NAV Server to open the Properties dialog box for the service, and then click the Log On tab.

  6. Click This account on the Log On tab.

  7. Type NT Authority\NetworkService in the first text box.

  8. Clear the entries in both the Password and Confirm password fields.

  9. Click OK to exit the Properties dialog box for the new service.

  10. In the Services snap-in, right-click Microsoft Dynamics NAV Server, and then click Start.

  11. Right-click Microsoft Dynamics NAV Server Instance 2, and then click Start.

    You now have two instances of the Microsoft Dynamics NAV Server service running on the same computer.

Expand image Testing the Second Service

Simon wants to test his second service by connecting to it from the RoleTailored client and by making a change to the data in one database.

To connect the RoleTailored client to a second service.

  1. Open the RoleTailored client that you have installed on a separate computer.

  2. In the Role Center menu bar, click Microsoft Dynamics NAV, and then click Select Server.

  3. In Server Name, add the number 2 to the DynamicsNAV value so that it is DynamicsNAV2.

  4. Click Connect.

  5. Select CRONUS International Ltd. from the Companies list.

    Unless you have already installed additional databases, the demo database is the only one available and is automatically selected.

    Click Connect, and then start working with your database.

Expand image Creating a Second Web Services Server on a Single Computer

You can adapt the procedure that is described in this walkthrough to create a second Microsoft Dynamics NAV Web services server on a single computer. Whether a service that you create manually is a standard Microsoft Dynamics NAV Server service or a Microsoft Dynamics NAV Web services service is determined by the name you give the service. If the name starts with "MicrosoftDynamicsNavWS", then the resulting service will be a Web service. If the name starts with anything else, then it will be a standard Microsoft Dynamics NAV Server service, which is a service serving RoleTailored clients.

For more information, see Creating a web service manually, the importance of the name you give it, and a few small things to remember on the Microsoft Dynamics NAV Team Blog.

Expand image Next Steps

Simon is satisfied that the two Microsoft Dynamics NAV Server services are working correctly. The next steps that he could take are:

  • Setting up two SQL Server databases on the computer running SQL Server.

  • Configuring the two Microsoft Dynamics NAV Server services to connect to different databases.

Expand image See Also

Tasks

Walkthrough: Installing the Three Tiers On Two Computers
Walkthrough: Installing the Three Tiers on Three Computers


Walkthrough: Setting Up Outlook Synchronization

Walkthrough: Setting Up Outlook Synchronization

You can synchronize data, such as to-dos, contacts, and tasks, between Microsoft Dynamics NAV 2009 and Microsoft Office Outlook. This enables users who rarely connect to Microsoft Dynamics NAV, such as salespeople who work out of the office, to keep their Microsoft Dynamics NAV data current. For example, a sales manager can set a meeting for a salesperson as a to-do in Microsoft Dynamics NAV, and that salesperson can view or edit the meeting from his or her Outlook calendar.A salesperson can also add a new contact in Outlook, and that contact is added to the company's Microsoft Dynamics NAV database.

Within Microsoft Dynamics NAV, you define the mapping between Microsoft Dynamics NAV entities and Outlook items. You then specify which entities users will synchronize.

The Microsoft Office Outlook Add-In for Microsoft Dynamics NAV is required to set up and use synchronization. Outlook must be set up and configured for users before the add-in is installed. If it is not, then the add-in may not display correctly. You must also set up either a Web service or an Application Server connection. This process is described in this walkthrough.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Setting up Microsoft Dynamics NAV synchonization in a multiple user environment.

  • Configuring Microsoft Dynamics NAV for Outlook synchronization.

  • Mapping Microsoft Dynamics NAV Entities to Outlook items.

    • Assigning synchronization entities to synchronization users.

    • Applying change log settings.

  • Setting conditions for entities.

  • Setting up Web services or an Application Server connection between Outlook and Microsoft Dynamics NAV.

  • Configuring synchronization in Outlook.

    • Applying synchronization settings.

    • Establishing the connection using either Web services or Application Server.

    • Setting up synchronization folders.

    • Setting a filter to exclude Outlook contacts from synchronizing with Microsoft Dynamics NAV.

    Note Note

    When you complete the setup and configuration of Outlook synchronization that is described in this walkthrough, you can test your setup by performing the steps that are described in, "Walkthrough: Synchronizing Information Between Outlook and Microsoft Dynamics NAV," which is located in the Microsoft Dynamics NAV online Help.

Expand image Setting Up Synchronization in a Multiple User Environment

Although this walkthrough does not describe setting up and using the Outlook add-in with a multiple-user environment, it is possible to do so. If the Outlook add-in needs to be used by multiple users on the same machine, such as in a terminal services scenario, then the following steps are recommended:

  1. Before installing the add-in, ensure that Outlook is properly installed for all the users who need the add-in.

  2. Install the Outlook Add-in from the Microsoft Dynamics NAV 2009 product media, and ensure that the installation is for all users.

For best results, install Microsoft Dynamics NAV 2009 and the Outlook add-in on a machine that has not had Microsoft Dynamics NAV 2009 installed and then uninstalled on it before.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Office Outlook installed and configured for you as a user.

  • One of the following Microsoft Dynamics NAV 2009 installations. Make sure that each listed component is installed.

    Installation that connects using Web services

    • RoleTailored client

    • Server

      • Microsoft Office Outlook Integration

    • SQL Server option

      • Demo Database

    • Classic client

      • Microsoft Office Outlook Integration

    • Microsoft Office Outlook Add-In
    Installation that connects using Application Server

    • RoleTailored client

    • SQL Server option

      • Demo Database

    • Classic client

      • Microsoft Office Outlook Integration

    • Application Server

      • Microsoft Office Outlook Integration

    • Microsoft Office Outlook Add-In

    For more information, see How to: Choose Components to Install.

Expand image Configuring Microsoft Dynamics NAV for Outlook Synchronization

Before you begin working with synchronization setup, ensure that you are a Windows Login user with super role permissions.

To define synchronization users

  1. Open the Classic client.

  2. On the Tools menu, point to Security, and then click Windows Logins.

  3. If you are not already listed in the Windows Logins window, then add yourself, click Roles, and then assign Super as the Role ID for your Windows login.

    Note Note

    You can use any role that enables you to add a salesperson and modify data in the Outlook Synch. Entities and Outlook Synch. User Setup tables.

Add yourself as a salesperson in Microsoft Dynamics NAV so that you can assign synchronization entities to yourself, and then test your setup.

To add yourself as a salesperson

  1. In the RoleTailored client, click Departments, click Sales & Marketing, click Sales, and then under Lists, click Salespeople.

  2. Click New, and then fill in the following fields in the New Salesperson/Purchaser card.

    Field Description

    Code

    Your initials.

    Name

    Your name as defined in your Outlook profile.

    E-mail

    Your e-mail address as defined in your Outlook profile.

  3. Click OK.

Expand image Mapping Microsoft Dynamics NAV Entities to Outlook Items

You begin synchronization setup by identifying the Microsoft Dynamics NAV objects that will be synchronized. When you open the Outlook Synch. Entities window for the first time, you may receive a message that asks for permission to connect to the Outlook synchronization .config file that is installed with the Outlook add-in. Select the option that always allows you to connect.

The following table lists the entities that are set up by default and the Outlook item types that they map to:

Microsoft Dynamics NAV entities | Outlook items
Contacts: Company or Person Contacts | Contacts
Contacts: Salesperson | Contacts
To-do type: Blank or Phone | Tasks
To-do type: Meeting | Meeting

To set up synchronization entities

  • Click Departments, click Administration, click Application Setup, click Microsoft Office Outlook Integration, and then click Outlook Synch. Entities.

    The default synchronization entities are sufficient for this walkthrough. However, if you want to add an entity, then in the Outlook Synch. Entities window, click New. In the New Outlook Synch. Entity window, add the information for the new entity that you want to map to an Outlook item. For more information, see the Microsoft Dynamics NAV Application Help.

After you have set up entities to synchronize with Outlook items, you assign users to the entity that they want to synchronize. In the following procedure, assign yourself as the user that is associated with the default entities.

When setting up synchronization, you can first assign a user to one or two entities and then continue with the setup to test that your connection works.

To assign synchronization entities to users

  1. Open the Outlook Synch. User Setup window.

  2. Click New, and in the Outlook Synch. User Setup window, click the User ID drop-down arrow, and then click your User ID.

  3. Click the Synch Entity Code drop-down arrow, and then add synchronization entities in the following order, with the User ID set to yourself:

    1. Add CONT_COMP. Leave the No. of Elements field at 0.

    2. Add CONT_PERS. Leave the No. of Elements field at 0.

    3. Add Cont_SP. Leave the No. of Elements field at 0.

    4. Add APP.

      For APP, click the No. of Elements field to open the Outlook Synch. Setup Details window.

      Click New, click the line under Outlook Collection, click Recipients, and then click OK. Add another line for the Outlook collection Links. Click OK.

    5. Add Task.

      For Task, click the No. of Elements field to open the Outlook Synch. Setup Details window.

      Click New, click the line under Outlook Collection, click Links, and then click OK.

  4. Click OK. The elements that you have added will be updated after you apply the change log settings.

You must activate the change log to enable tracking of the changes that you made to the synchronization entities.

To apply change log settings

  1. In the Outlook Synch. User Setup window, click Related Information, point to Setup, and then click Register in Change Log Setup.

  2. Add a filter for each entity as follows:

    • Where Code is <Synch. Entity Code name>.

    • And Code is <Synch. Entity Code name>, and so on.

  3. Click OK. Close and reopen the company to enable the change log settings.

    Note Note

    Run the Register in Change Log Setup batch job each time that you add or change a synchronization entity to ensure that the changes are collected for the required fields.

Expand image Setting Conditions for Entities

You should set conditions for the TASK and APP entities. This helps limit whose tasks and meetings are placed on your Outlook calendar. For example, you could set a condition to retrieve only those meetings and tasks that involve you as the salesperson and that you own. Meetings and tasks need a Meeting Organizer or Task Owner, so you must create a condition. If you do not, then you cannot synchronize meetings withMicrosoft Dynamics NAV.

To configure conditions

  1. In the navigation pane, click Departments, click Administration, click Application Setup, click Microsoft Outlook Integration, and then click Outlook Synch. User Setup.

  2. Select the line with the APP entity, and then click in the Condition field.

  3. In the Outlook Synch. Filters -Condition window, in the Field Name field, select Salesperson Code. In the Value field, add the code for the salesperson.

  4. Repeat steps 1 through 3 for the TASK entity.

Otherwise, setting conditions for other entities is not mandatory, but you should do it to prevent mass data transfer to a local mailbox or a Public Folder.

Expand image Setting Up Web Services or Application Server Connection

You must set up either a Web services or an Application Server connection between Microsoft Dynamics NAV and Outlook. Perform either procedure to set up a connection.

To set up a Web services connection

  1. Ensure that Web services are running:

    1. Click Start, point to All Programs, point to Administrative Tools, and then click Services.

    2. Right-click Microsoft Dynamics NAV Business Web Services, and then on the shortcut menu, click Start.

    3. Close the window.

  2. Open the RoleTailored client.

  3. In the navigation pane, click Departments, click Administration, click IT Administration, click General, and then click Web Services.

  4. Locate the DynamicsNAVsynchOutlook service, double-click to open it, and then select the Published check box. Click OK.

To set up an Application Server connection

  1. On the Start menu, point to All Programs, point to Administrative Tools, and then click Application Server Manager for Microsoft Dynamics NAV.

  2. Right-click Application Server for Microsoft Dynamics NAV Manager, and on the shortcut menu, point to New, and then click Application Server.

  3. In the New Application Server for Microsoft Dynamics NAV dialog box, add values for your server's Host Name and Service Name fields. The host name is generally your database server name. You can find your service name as follows:

    1. Click Start, point to Administrative Tools, and then click Services.

    2. Right-click Application Server for Microsoft Dynamics NAV Classic <machine name>-SQL, and on the shortcut menu, click Properties. The service name is displayed on the General tab.

  4. Click OK.

  5. In the NASMSnapIn window, a Microsoft Dynamics NAV 2009 form is displayed. You may need to expand the snap-in tree to get to the form. Fill in the form as follows:

    Field Description

    Database Server Name

    Your SQL Server database server name

    Database

    Demo Database NAV

    Company Name

    CRONUS International Ltd.

    Start-Up Parameter

    OSYNCH

    Net Type

    TCP/IP Sockets

    Object Cache size

    8000

  6. Click Apply the Settings, and then click Start Service.

  7. Click Start, point to Administrative Tools, and then click Services. In the Services window, right-click Application Server for Microsoft Dynamics NAV Classic <machine name>-SQL, and on the shortcut menu, click Properties.

  8. On the Log On tab, select the This Account option, and then add your Windows login credentials, including your domain if your computer is part of a domain. Click Apply.

  9. Stop and restart the service to enable the login credentials.

Expand image Configuring Synchronization in Outlook

Now open Microsoft Outlook. The Microsoft Dynamics NAV Synchronization toolbar that is displayed in your Outlook client contains four buttons by default.

Toolbar button | Description
Synchronize | Start synchronization manually.
Settings | Configure synchronization, including automatic synchronization, conflict resolution, and connection, and set folders and filters for synchronization entities.
Troubleshooting | Resolve synchronization issues. If the Troubleshooting icon is red, then you have existing errors that must be fixed.
Connection State | Indicates whether you are connected. The icon displays a red X when you are not connected.

Applying Synchronization Settings

Begin by establishing synchronization settings in the Settings dialog box. You can set synchronization to run automatically and set how frequently that it should run. You can also set how conflicts should be resolved between Microsoft Dynamics NAV and Outlook when changes have been made in each application simultaneously.

Because you want to test your synchronization setup manually to ensure that it is working properly, you will not select the automatic synchronization setting. In addition, you will not select the automatic resolution setting at this time.

To set rules for synchronization

  1. In Outlook, on the Microsoft Dynamics NAV Synchronization toolbar, click Settings.

  2. On the General tab, select Show synchronization progress and Show synchronization summary.

  3. Select Resolve conflicts manually.

Establishing a Connection Between Microsoft Dynamics NAV and Outlook

On the Connection tab, you must select a type of connection. You must have a working connection before you proceed with the synchronization settings.

If you set up Web services, then use the following steps to establish your connection.

To establish a Web services synchronization connection

  1. In the Server Type area, select Microsoft Dynamics NAV Service Tier.

    In the Connection Type area, Web Service is automatically selected. Use the default Web service path that is displayed in the Web Service Path text box: http://localhost:7047/DynamicsNAV/WS/Codeunit/DynamicsNAVsynchOutlook

  2. In the Company Name box, select CRONUS International Ltd.

  3. Click Test Connection.

    If your connection succeeds, then you receive a message, and the red "X" is removed from the icon on the Connection State toolbar button. If your connection does not succeed, then you receive an error message. To resolve the error, stop and restart the Web service.

If you set up Application Server, then use the following steps to establish your connection.

To establish an Application Server synchronization connection

  1. In the Server Type area, select Microsoft SQL Server.

  2. In the Connection Type area, C/FRONT.NET is automatically selected. In the Server Name box, select the name of your SQL Server.

  3. In the Database Name box, select Demo Database NAV (6-0).

  4. In the Company Name box, select CRONUS International Ltd..

    If your connection succeeds, then you receive a message, and the red "X" is removed from the icon on the Connection State toolbar button. If your connection does not succeed, then you receive an error message. To resolve the error, stop and restart the Application Server service.

Defining Synchronization Folders

Each Microsoft Dynamics NAV entity must be mapped to folders that you create for this purpose in Outlook. The folders must map to the entity type. This means that for contacts, the folder must be created in Outlook Contacts, for tasks, the folder must be created in Outlook Tasks, and so on. If you create a new entity, you set the Outlook item that that entity maps to. You can verify what Outlook item you set by double-clicking the entity in the Outlook Synch. Entities window in Microsoft Dynamics NAV.

To set folders for synchronization entities

  1. Create a new folder in Outlook for each entity that you have set up for synchronization. For example, create a Company Contacts folder, and set the folder to contain Contact Items. The following table lists the default entities and the type of folder to create.

    Microsoft Dynamics NAV entities Outlook folder item types

    Microsoft Dynamics NAV Contacts of the Company type

    Contacts

    Microsoft Dynamics NAV Contacts of the Person type

    Contacts

    Microsoft Dynamics NAV Salespeople

    Contacts

    Microsoft Dynamics NAV Meetings

    Calendar

    Microsoft Dynamics NAV Tasks

    Tasks

  2. In the Settings dialog box, click the Folders tab.

    The entities that you set for synchronization are displayed in the Synchronization Folders area. If you add a new entity in Microsoft Dynamics NAV, then it is displayed in this list.

  3. Click Browse, and then map each entity to the folder you created for it. Click Apply.

Setting Filters

You set filters to define any items that you do not want to be synchronized. For example, if you have a personal appointment or personal contacts that you do not want to be synchronized with your Microsoft Dynamics NAV contacts, then you can filter for those. In this scenario, you filter to exclude personal contacts from synchronization by excluding contacts that contain home telephone numbers.

To set a filter

  1. On the Filters tab, on the Microsoft Dynamics NAV Contacts of the Person type line, click Edit.

  2. In the Field Name box, select HomeTelephoneNumber.

  3. In the Condition box, select is not empty, and then click Add to List.

    Contacts with home telephone numbers will not be synchronized. Click Apply, and then click OK.

  4. On the Microsoft Dynamics NAV Synchronization toolbar, click Synchronize.

    The Synchronization Progress message is displayed. When synchronization is complete, you can view the details for the synchronization.

Expand image Next Steps

You have completed the required setup for synchronizing information between Microsoft Dynamics NAV and Microsoft Office Outlook. To test your setup, see Walkthrough: Synchronizing Information Between Outlook and Microsoft Dynamics NAV.

Expand image See Also

Tasks

Troubleshooting: Microsoft Office Outlook Integration and Synchronization

Concepts

Configuring Microsoft Dynamics NAV 2009
Configuring Application Server


Walkthrough: Synchronizing Information Between Outlook and Microsoft Dynamics NAV

Walkthrough: Synchronizing Information Between Outlook and Microsoft Dynamics NAV
See Also
CollapseAll image

You can set up synchronization between Microsoft Dynamics NAV and Microsoft Outlook, so that information about meetings, to-dos, and contacts can be shared between team members and updated across the two products. For example, a salesperson working in the field can create a new meeting in her company's calendar using Outlook, and then her manager in the corporate office can see that to-do on in Microsoft Dynamics NAV.

The synchronization framework provides default mapping between the Microsoft Dynamics NAV contacts, salesperson, and to-dos and Microsoft Outlook contacts, tasks, and meetings. You can synchronize the entities either manually or automatically at regular intervals.

One of the strengths of the Microsoft Dynamics NAV Outlook synchronization feature is that it can be customized without adding code. It is fairly simple to add additional fields in order to optimize synchronization.

The default setup contains mapping for five different Microsoft Dynamics NAV entities:

  • To-dos of type Meeting

  • Contacts of the Company type

  • Contacts of the Person type

  • Salespeople

  • To-dos of type blank or Phone

Companies might want to add additional fields to this mapping. For more information, see the section "Customizing Synchronization Fields" in this walkthrough.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating a to-do, and synchronizing it with Outlook.

  • Handling a conflict between different data on the same record.

  • Customizing fields that are being synchronized.

Note Note

A conflict will only appear if changes have been made in both applications after the last synchronization. Therefore, some steps in this walkthrough force a conflict so you can practice solving it. In this case, you enter two different phone numbers for the same contact, and then handle the conflict.

Roles

You play the following roles during this walkthrough:

  • Michael, the account manager

  • David, the sales representative

Note Note

So that you can quickly begin performing the following procedures, you will use your own Microsoft Dynamics NAV user settings and Outlook account, rather than setting up Michael and David as new users in the CRONUS database. See the "Prerequisites" section that follows for information about the required Outlook integration setup.

Prerequisites

To complete this walkthrough, you will need:

  • To perform the steps in the walkthrough: Walkthrough: Setting Up Outlook Synchronization

  • To ensure that NAS or Web services are running, depending on whether you will connect using CFRONT or Web services.

  • In Microsoft Dynamics NAV:

    • Outlook Integration is installed.

    • CRONUS International Ltd. demo database is installed.

    • Your name added as a salesperson, with your name and e-mail address defined exactly as they are in your Outlook profile.

    • Your name assigned as a user to synchronization entities.

  • In Outlook:

    • Microsoft Dynamics NAV Synchronization toolbar is displayed.

    • The connection between Microsoft Dynamics NAV and Outlook is working. To test the connection, click Settings, and then on the Connection tab, click Test Connection.

Expand image Story

Michael is an account manager for CRONUS International Ltd. He works primarily in the CRONUS office, and uses Microsoft Dynamics NAV. His coworker, David, is a sales representative who works mainly in the field and uses Outlook to track contacts, tasks, and appointments. Because Michael and David share information, they synchronize their information regularly throughout the day. This enables Michael to set appointments for David, while also keeping track of David's activities in the field.

In this scenario, Michael creates an appointment for David to meet with an existing customer. When David synchronizes, he sees the meeting that Michael has created. He does not think that he can drive to the location in time, so he moves the meeting to another day in his Outlook calendar. He synchronizes again and the changes are updated in Microsoft Dynamics NAV, so that Michel can track the change.

Michael attempts to call the contact, but the phone number is incorrect because someone else has entered a new number in Outlook and not yet synchronized with Microsoft Dynamics NAV. Michael reviews the conflict details, determines that the problem is related to the phone number, and resolves the conflict.

Michael also realizes that he needs to add some additional fields to the entities that are synchronized. He adds the territory code fields as user-defined fields to the company contact information so that they will be displayed in both Outlook and Microsoft Dynamics NAV.

Expand image Performing a Synchronization

First, Michael sets an appointment for David to meet with a customer by creating a to-do in Microsoft Dynamics NAV, and then synchronizing with Outlook, so that the appointment is displayed on the team calendar.

To create a to-do and synchronize it with Outlook

  1. In Microsoft Dynamics NAV, click Departments, click Sales & Marketing, click Sales, and under Lists, click Contacts.

  2. In the Contacts list, open the contact card for A. Gibson's Law Firm, CT100006.

  3. Change the Salesperson code to your initials.

  4. On the Related Information menu, point to Contact, and then click To-dos.

  5. On the To-do list, click Create To-do.

  6. In the Create To-do wizard, add the following information:

    • Set the to-do as type Meeting.

    • Add a short description, such as "talk proposal."

    • Set the meeting for today and add a start time.

  7. Click Next, and the Step 2 pane is displayed with your name as the To-do organizer, and A. Gibson's Law Firm as a required attendee.

  8. Click Finish.

  9. In Microsoft Outlook, click Calendar to open the calendar view, and then in the My Calendars list, open your Microsoft Dynamics NAV calendar.

  10. On the Microsoft Dynamics NAV toolbar, click the Synchronize button to activate synchronization.

    The synchronization runs, and you can see the appointment that you created on the shared calendar.

David checks the synchronized calendar for Microsoft Dynamics NAV updates. He sees the appointment and adjusts the time to fix the conflict.

To change a meeting request in Microsoft Dynamics NAV and synchronize with Outlook

  1. In your Outlook calendar, move the appointment created in Microsoft Dynamics NAV to another day, and then click the Synchronize button to active synchronization again.

  2. Now, open Microsoft Dynamics NAV and navigate to the contact card for CT100006.

    The Next To-do Date field lists the new date of the meeting. You can click the date to open the to-do list, and see the changes that you made to the appointment.

Expand image Handling a Synchronization Conflict

Michael decides to call the customer to let them know that David has made changes to the appointment. He finds that there is a conflict in the contact information, and troubleshoots the conflict. Though this scenario demonstrates how to solve the conflict manually, he could also set up synchronization to handle conflicts automatically. For more information, see Setting Up Synchronization Conflict Resolution Options in the RoleTailored Client Help.

To handle a conflict

  1. Click Settings to open the Settings dialog box.

    The Settings dialog box presents several options for solving conflicts, including options to automatically replace Outlook items with Microsoft Dynamics NAV records, or to automatically replace Microsoft Dynamics NAV records with Outlook items.

  2. Be sure the Resolve conflicts manually option is selected, and close the Settings dialog box.

  3. In Microsoft Dynamics NAV, open the contact card for A. Gibson's Law Firm, CT100006, and add the phone number 1234567.

  4. Open Outlook and find the contact for A. Gibson's Law Firm.

  5. Change the phone number to 1224567, so that it is different from the number that you entered in Microsoft Dynamics NAV.

  6. Click the Synchronize button to activate the synchronization.

  7. Then, click the Troubleshooting button, and click the Conflicts tab.

    The conflict is listed here. You can either click Show Outlook Item or Details to see more details about the conflict.

  8. Click Details.

    The Conflict Details dialog box displays a list of the fields that are mapped between the two entities. The conflict is listed in red, which enables you to see that the phone number is creating the conflict.

    Click Replace Outlook Item, select the item from the list, and then click OK.

Expand image Customizing Synchronization Fields

Because CRONUS has a lot of foreign contacts and actively uses the territory code, Michael decides to add this field to the synchronization mapping.

To add fields to the existing setup

  1. In Microsoft Dynamics NAV, click Departments, and under Administration, click Application Setup. Click Microsoft Office Outlook Integration, and then click Outlook Synch Entities.

    The Outlook Synch. Entity window contains the definition of the mapping between contacts in Microsoft Dynamics NAV and contacts in Microsoft Outlook.

  2. In the Code field, double-click CONT_COMP.

    All the fields that are mapped between the two programs are listed in this form. To add the requested field, add a line in this form and choose the fields you want to include in the synchronization.

  3. On the Related Information menu, point to Synch Entity, and then click Fields.

  4. Click New, and then select Field No. 15, Territory Code.

  5. Because there are no comparable Outlook properties to map this to, select the User Defined check box for the Territory Code field.

    Because entries in the Change Log are used to identify changes in Microsoft Dynamics NAV you must add this field to the change log as well.

  6. On the Related Information menu, point to Sync. Entity, and then click Register in Change Log Setup. Click OK.

  7. Click OK again in the dialog box that appears.

    To ensure that the added territory code appears in Microsoft Outlook, you must create and synchronize a new contact. Changes in the synchronization setup are only shown for newly synchronized items.

  8. In Sales & Marketing, click Order Processing, and then click Contacts.

  9. Click New, and create a new contact of the type Company.

  10. Add a new customer name.

  11. Click the Foreign Trade tab, and then in the Territory Code field, select a territory code.

  12. Click OK.

  13. Open Microsoft Outlook, and start synchronization.

  14. When the synchronization is finished, in Microsoft Outlook, open the new contact you created in Microsoft Dynamics NAV.

  15. On the Contact tab, in the Show group, click All fields and then select the User-defined fields in this item option.

    Here, you can see both the salesperson code and the territory code are included in the Outlook contact information.

    Now that you have completed this walkthrough, you can establish synchronization entities and begin synchronizing between Outlook and your company's Microsoft Dynamics NAV implementation.

Expand image See Also

Other Resources

Microsoft Dynamics NAV 2009 Business Process Walkthroughs


Configuring Microsoft Dynamics NAV 2009

Configuring Microsoft Dynamics NAV 2009

This section identifies components you can pre-configure in Microsoft Dynamics NAV 2009 Setup. It also provides information about settings for individual components, and, for some components, identifies another document where you can find such information.

Note Note

"Configuration" is a broad term and you will not find everything that it encompasses in this online Help system. The focus here is on components that you can configure while running Setup.

Components That You Can Configure In Setup

You can configure some Microsoft components in Microsoft Dynamics NAV 2009 Setup. You can then either proceed to install software with Setup, or save all configuration information to a Setup configuration file for future use. For more information, see How to: Preconfigure Components.

When you install a component that you have pre-configured in Setup, the configuration information is transferred to the appropriate component configuration file. For example, if you pre-configure the NAV Server in Setup, the relevant configuration information is transferred, upon installation, to the CustomSettings.config file. This file is stored on the NAV Server computer in Program Files\Microsoft Dynamics NAV\60\Service.

Configuring the RoleTailored Client

Configuring Microsoft Dynamics NAV Server

Configuring Database Components

Configuring Application Server

Configuring Classic Database Server

See Also

Tasks

Walkthrough: Setting Up Outlook Synchronization
How to: Configure Windows Services
How to: Create Users
Walkthrough: Setting Up Document Approvals

Concepts

Configuring Automated Data Capture System
Configuring Microsoft SQL Server
Profiles and Role Centers


Configuring the RoleTailored Client

Configuring the RoleTailored Client

The RoleTailored client is a component of the RoleTailored Architecture in Microsoft Dynamics NAV 2009.

As you run Microsoft Dynamics NAV 2009 Setup, you can provide configuration information for the RoleTailored client. This information is then saved in the ClientUserSettings.config file.

A separate instance of the ClientUserSettings.config file is maintained for each client user. On Windows Server 2003 or Windows XP, the location of this file is Documents and Settings\<username>\Local Settings\Application Data\Microsoft\Microsoft Dynamics NAV.

On Windows 7, Windows Vista, or Windows Server 2008, the location is Users\<username>\AppData\Local\Microsoft\Microsoft Dynamics NAV.

This file is hidden by default. Change your folder options in Windows Explorer to view hidden files before you edit the ClientUserSettings.config file.

Configuring the RoleTailored Client in Setup

You can configure the RoleTailored client when running Microsoft Dynamics NAV 2009 Setup. You must first select the RoleTailored client as a component to install. To do this, select one of the following Installation Options that includes Microsoft Dynamics NAV Server:

  • Client Option

  • Developer Environment Option

You can also customize your installation and customize the list of components to install. For more information, see How to: Choose Components to Install.

After you specify an installation option or customize your component list, the Specify parameters pane is displayed in Setup. Click RoleTailored Client to open the Installation Parameters pane. The underscore indicates that this component is configurable.

Settings

The list of parameters that you see in the Specify parameters pane depends on which components that you have selected for configuration. The following parameters pertain to the RoleTailored client.

Parameter Description

Server Name

The name of the computer running Microsoft Dynamics NAV Server for this client.

Default value: Blank if you install using the Client installation option or localhost if you install using the Developer Environment installation option or a custom installation.

Server Port

The listening TCP port for the computer running Microsoft Dynamics NAV Server for this client.

Default value: 7046

Caution note Caution

If you specify an invalid port number in Setup, then the RoleTailored client cannot connect to Microsoft Dynamics NAV Server. You will receive the following message when you attempt to open the RoleTailored client:

The program could not create a connection to the server. Do you want to try again?

If you click No, then the Select Server window opens. Correct the port number by typing a string in this format in the Server name field:

CopyCode image Copy Code
servername:port/ServerInstance

Click Apply when you have finished entering values to return to the Specify parameters pane in Setup.

After you finish running Setup, you can modify Microsoft Dynamics NAV Server settings.

Configuring the RoleTailored Client After Installing

After you install the RoleTailored client, configuration settings are stored in the ClientUserSettings.config file. If you have configured the RoleTailored client in Setup, then your setting values are included in this file.

In addition to the settings that you can configure in Setup, the ClientUserSettings.config file contains other settings for the RoleTailored client. After you modify the ClientUserSettings.config file, you must restart the RoleTailored client for changes to take effect.

Settings in the ClientUserSettings.config File

The ClientUserSettings.config file is an .xml file that you can edit with any text editor. Quotation marks are required for all values.

Note Note

The ClientUserSettings.config file is hidden by default.

The following settings are available.

Setting Description

Server

The name of the computer running Microsoft Dynamics NAV Server for this client.

Default value: Empty string if you installed using the Client installation option or localhost if you installed using the Developer Environment installation option or a custom installation.

ServerInstance

The name of the computer running Microsoft Dynamics NAV Server.

Default value: DynamicsNAV

You may need to modify this value if you have more than one instance of Microsoft Dynamics NAV Server installed on a single-server computer. For more information, see Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer.

ServerPort

The listening TCP port for the computer running Microsoft Dynamics NAV Server for this client.

Default value: 7046

ProtectionLevel

The security services for protecting the client/server data stream. This value must match the value that is specified in the Microsoft Dynamics NAV Server configuration file. For more information, see Configuring Microsoft Dynamics NAV Server.

Default: EncryptAndSign

Values: EncryptAndSign, Sign, None

CompressionThreshold

The threshold in memory consumption at which the RoleTailored client starts compressing datasets, in kilobytes.

Default: 64

ChunkSize

The default size for a chunk, in kilobytes.

Default: 28.

The range of values is from 4 to 80.

AllowNtlm

The value for whether NTLM fallback is permitted for authentication.

To require Kerberos authentication, set this value to false.

Default value: true

ServicePrincipalNameRequired

If this parameter is set to true, then the client can only connect to a Microsoft Dynamics NAV Server service that has been associated with a service principal name (SPN).

If this parameter is set to false, then the client attempts to connect to the configured Microsoft Dynamics NAV Server service regardless of whether that service is associated with an SPN.

For more information about SPNs, see How To: Set Up Delegation.

Default: false

OpenConnectionTimeout

The maximum amount of time to wait before determining that the client attempt to connect to Microsoft Dynamics NAV Server has failed.

Time span format: [dd.]hh:mm:ss[.ff]

Where:

  • dd: days

  • hh: hours

  • mm: minutes

  • ss: seconds

  • ff: fractions of a second

You can also use MaxValue to indicate no timeout.

Default: 00:00:30

UnknownSpnHint

This is a parameter the RoleTailored client can use to establish connections more quickly. Do not modify this parameter.

UrlHistory

A comma-delimited list of servers that is displayed in the Select Server window when you click the drop-down arrow in the Server name field.

This parameter is not present after you install the RoleTailored client, but it is created and populated once the user enters a server name in the field.

You can create and populate this field after installing the RoleTailored client. This gives the user a list of servers from which to choose.

Example:

CopyCode image Copy Code
<add key="UrlHistory" value="localhost, dev:7046/DynamicsNAV, sales:7046/DynamicsNAV"/>

FilterAsYouTypeAutomaticLookupEnabled

This setting is not present by default in the ClientUserSettings.config file. If you need to set this parameter, then you must first add it manually.

The filter-as-you-type (or find-as-you-type) feature displays a drop-down list of available choices as you type text into a field in the RoleTailored client. Some users may find this feature distracting or counterproductive, such as if the drop-down list appears whenever the user pauses when typing. To disable this feature, edit the ClientUserSettings.config file to add this parameter with a value of false:

CopyCode image Copy Code
<add key="FilterAsYouTypeAutomaticLookupEnabled" value="false"></add>

See Also

Concepts

Configuring Microsoft Dynamics NAV Server


Configuring Microsoft Dynamics NAV Server

Configuring Microsoft Dynamics NAV Server

Microsoft Dynamics NAV Server is a component of the RoleTailored Architecture in Microsoft Dynamics NAV 2009.

When you run Microsoft Dynamics NAV 2009 Setup, you can provide configuration information for Microsoft Dynamics NAV Server. This information is then written by Setup to the CustomSettings.config file. If you install Microsoft Dynamics NAV Server to the default destination, then you can find the CustomSettings.config file after installation at C:\Program Files\Microsoft Dynamics NAV\60\service.

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Configuring Microsoft Dynamics NAV Server in Setup

You can configure Microsoft Dynamics NAV Server when running Microsoft Dynamics NAV 2009 Setup. You must first select Microsoft Dynamics NAV Server as a component to install. To do this, select one of the following Installation Options that includes Microsoft Dynamics NAV Server:

  • Server Option installs Microsoft Dynamics NAV Server without any other components.

  • Developer Environment Option installs Microsoft Dynamics NAV Server with other components that are used for developing client applications.

You can also customize your installation and the list of components to install. For more information, see How to: Choose Components to Install.

After you specify an installation option or customize your component list, the Specify parameters page is displayed. Click Server to open the Installation Parameters page. The underscore indicates that this component is configurable.

Settings

The parameter list that you see in the Specify parameters pane depends on which components you have selected for configuration. The following parameters pertain to Microsoft Dynamics NAV Server.

Parameter | Description
Server Name | The computer running Microsoft Dynamics NAV Server.
Server Port | The listening TCP port for Microsoft Dynamics NAV Server, which becomes part of the server's URL. Default value: 7046 Valid range: 1-65535
SQL Server | The computer running SQL Server.
SQL Database | The SQL Server database.
Web Service Port | The listening HTTP port for Microsoft Dynamics NAV Web services. Default value: 7047 Valid range: 1-65535

Click Apply when you have finished entering values to return to the Specify parameters page in Setup.

After you finish running Setup, you can modify Microsoft Dynamics NAV Server settings by editing the CustomSettings.config file.

Configuring Microsoft Dynamics NAV Server After Installation

After you install Microsoft Dynamics NAV Server, configuration settings are stored in the CustomSettings.config file. By default, this file is located in C:\Program Files\Microsoft Dynamics NAV\60\Service. If you have configured Microsoft Dynamics NAV Server in Setup, then your setting values are also included in this file.

In addition to the settings that you configure in Setup, the CustomSettings.config file contains additional settings for Microsoft Dynamics NAV Server. After you modify the CustomSettings.config file, you must restart the Microsoft Dynamics NAV Server service. For more information about working with Windows services, see How to: Configure Windows Services.

Settings in the CustomSettings.config File

The CustomSettings.config file is an .xml file that you can edit with any text editor. It contains the following settings. Quotation marks are required for all values.

Setting Description

NetType

The network protocol used to access the database.

Default value: Default

Valid values: Default, NamedPipes, Sockets

DatabaseServer

The computer running SQL Server.

DatabaseInstance

The name of the SQL Server database instance to connect to.

DatabaseName

The name of the SQL Server database.

ServerInstance

A name that identifies the instance of Microsoft Dynamics NAV Server.

Default: DynamicsNAV

You may need to modify this value if you have more than one Microsoft Dynamics NAV Server instance installed on a single server computer. For more information, see Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer.

ServerPort

The listening TCP port for Microsoft Dynamics NAV Server, which becomes part of the server URL.

Default value: 7046

Valid range: 1 - 65535

WebServicePort

The listening HTTP port for Microsoft Dynamics NAV Web services.

Default value: 7047

Valid range: 1 - 65535

WebServiceSSLEnabled

The parameter for whether SSL (https) is enabled for the Web service port.

Default value: false

Values: true, false

WebServicesMaxMsgSize

The maximum permitted size of a Web services request, in kilobytes.

Default: 512

WebServicesUseNTLMAuthentication

Set this parameter to true if you are using PHP or Java to initiate a Web services connection to Microsoft Dynamics NAV and if the RoleTailored client, Microsoft Dynamics NAV Server, and SQL Server database are all on separate computers. See How to: Configure Web Services with Delegation.

Default value: false

OperationTimeout

The maximum time that Microsoft Dynamics NAV Server can take to return a call from the client.

Time span format: [dd.]hh:mm:ss[.ff]

Where:

  • dd: days

  • hh: hours

  • mm: minutes

  • ss: seconds

  • ff: fractions of a second

You can also use MaxValue to indicate no timeout. This is the default value.

ProtectionLevel

The security services for protecting the client/server data stream.

All RoleTailored clients connecting to the Microsoft Dynamics NAV Server must have the same ProtectionLevel value in their ClientUserSettings.config files. See Configuring the RoleTailored Client.

Default: EncryptAndSign

Values: EncryptAndSign, Sign, None

MaxConcurrentCalls

The maximum number of concurrent client calls that can be active on Microsoft Dynamics NAV Server.

Default: 40

Range: 1 - 2,147,483,647

To disable this setting, use a value of MaxValue.

MaxConcurrentConnections

Specifies the maximum number of concurrent client connections that the Microsoft Dynamics NAV Server accepts.

Default: 150

You can also use MaxValue to indicate no limit.

ClientReconnectPeriod

The period during which a client can reconnect to a running instance of Microsoft Dynamics NAV Server.

Time span format: [dd.]hh:mm:ss[.ff]

Where:

  • dd: days

  • hh: hours

  • mm: minutes

  • ss: seconds

  • ff: fractions of a second

Default: 00:10:00

You can also use MaxValue to indicate no limit on this period.

MaxNumberOfOrphanedConnections

Specifies the maximum number of orphaned connections to be kept alive simultaneously for the time that is specified by the ClientReconnectPeriod parameter.

A connect is said to be orphaned when the client is involuntarily disconnected from Microsoft Dynamics NAV Server.

Default: 20

You can also use MaxValue to indicate no limit.

CompressionThreshold

The threshold in memory consumption at which Microsoft Dynamics NAV Server starts compressing datasets, in kilobytes.

Default: 64

MetadataProviderCacheSize

The Metadata Provider cache size. The value specifies the number of objects to be cached. Set this value to 0 to disable caching.

Default: 150

MaxUploadSize

The maximum size of files that can be uploaded to or downloaded from Microsoft Dynamics NAV Server, in megabytes. Use this parameter to avoid out-of-memory errors.

Default: 5

EnableDebugging

The parameter for whether Microsoft Dynamics NAV Server starts with debugging mode enabled. If set to true, then this mode has three functions:

  • Upon first connection by a RoleTailored client, all C# files for the application are generated.

  • C# files are persisted between server restarts.

  • Application objects are compiled with debug information.

Default: false

MaxItemsInObjectGraph

The maximum number of objects to serialize or deserialize, in kilobytes.

Default: 128

ChunkSize

The default size for a chunk of data that is transferred between Microsoft Dynamics NAV Server and the RoleTailored client, in kilobytes.

Default: 28.

The range of values is from 4 to 80.

See Also

Tasks

Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer

Concepts

Enhancing Microsoft Dynamics NAV Server Security


Configuring Database Components

Configuring Database Components

The Database Components option is software you install on the computer running the SQL Server database to configure interaction between Microsoft Dynamics NAV 2009 and the SQL Server database.

What Setup actually installs with the Database Components option depends on whether it finds SQL Server already present on the computer:

  • If SQL Server is present, then Setup installs software that Microsoft Dynamics NAV requires for interacting with SQL Server.

  • If SQL Server is not present, then Setup installs Microsoft SQL Server 2005 Express Edition and software that Microsoft Dynamics NAV requires for interacting with SQL Server Express. SQL Server Express is best for prototyping and for demonstration purposes. Any production system that you design around SQL Server Express should be very small, with typically five users or fewer.

Configuring Database Components in Setup

When you are running Microsoft Dynamics NAV 2009 Setup, you can provide configuration information for the database components. You must first do one of the following steps in Setup:

  • Select Database Components on the Choose an installation option page.

  • Select SQL Server option from the Customize the installation page.

These actions are equivalent.

After you specify an installation option or customize your component list, you see the Specify parameters pane. Click SQL Server option to open the Installation Parameters page.

Settings

The exact list of parameters that you see in the Specify parameters pane depends on which components you have selected for configuration. The following parameters pertain to database components.

Parameter Description

SQL Server instance

Specifies the instance of SQL Server that Microsoft Dynamics NAV interacts with. If no value is provided, then Microsoft Dynamics NAV interacts with the default instance of SQL Server.

Note Note

If you specify a nondefault instance and Setup fails to connect to the database, then try prefixing the server computer name and a backslash to the instance name, such as serverName\instanceName.

SQL Database

Specifies the name of the database that Microsoft Dynamics NAV interacts with.

The default value is Demo Database NAV (6-0).

Replace Existing Database

Specifies what Setup should do if the demo database is already present in SQL Server.

With the default value (No), Setup completes with an error.

With this parameter set to Yes, Setup completes with no error.

See Also

Concepts

Database Components Option
Configuring Microsoft SQL Server


Configuring Microsoft SQL Server

Configuring Microsoft SQL Server

SQL Server is required by the Microsoft Dynamics NAV 2009 RoleTailored Architecture. The topics in this section describe various actions that you can take after installing Microsoft Dynamics NAV and SQL Server to integrate the two products:

  • Setting Database Owner and Security Administration Permissions

  • Enabling the Object Change Listener

  • Troubleshooting SQL Server Connection Problems

See Also

Concepts

Installation Considerations for Microsoft SQL Server

Other Resources

Installation Walkthroughs


Setting Database Owner and Security Administration Permissions

Setting Database Owner and Security Administration Permissions
See Also

If permissions are granted on a Microsoft Dynamics NAV database, the user can only perform database changes for that database. To allow a user to make changes to all databases in a SQL Server instance, grant permissions to the master database.

Database Changes that Require Elevated Permissions

Microsoft Dynamics NAV administrators should be granted the securityadmin Server Role in SQL Server Management Studio. The following table lists areas and actions that require elevated permissions.

Area Action Minimum permissions

Database

Create, test, alter, and delete

db_owner for Microsoft Dynamics NAV databases and the master database

Company

Create, rename, and delete

db_owner for Microsoft Dynamics NAV databases and the master database

Objects

Create, modify, and delete

db_owner for Microsoft Dynamics NAV databases and the master database

License

  • Upload to database

  • Upload to all databases on server

    Note Note

    For more information, see How to: Activate the License File.

db_owner for Microsoft Dynamics NAV databases and the master database

Users

Add and synchronize users

db_accessadmin for the master database; db_accessadmin and db_owner for Microsoft Dynamics NAV databases

In addition, you must provide additional privileges by following these steps:

  1. Open SQL Server Management Studio and connect to your SQL Server instance.

  2. On the File menu, point to New, and then click Query with Current Connection.

  3. Type the following SQL statements.

    CopyCode image Copy Code
    GRANT SELECT ON sysprocesses WITH GRANT OPTION TO [username]
GRANT VIEW SERVER STATE WITH GRANT OPTION TO [username]
GO

  4. Highlight the lines that you just typed and, on the Query menu, click Execute.

To grant permissions in SQL Server

  1. Open SQL Server Management Studio and connect to your instance of SQL Server.

  2. In the left pane, click Databases, select a database, click Security, and then click Users.

  3. In the Users pane, right-click the user that needs permissions, and on the shortcut menu, click Properties.

  4. Under Database role membership, select relevant privileges, and then click OK.

See Also

Concepts

Installation Considerations for Microsoft SQL Server


Enabling the Object Change Listener

The Object Change Listener component of Microsoft Dynamics NAV Server monitors the database for changes that are made to application objects, such as adding a new field to a page. When the Object Change Listener detects that a change has been made to an application object, it flushes the application object from the server-side cache, which causes clients to get a newer version from the database.

For the Object Change Listener to start, Microsoft Dynamics NAV Server must have permissions to the SQL Server database. If Object Change Listener cannot start because of permissions errors, then you cannot connect any clients to the server. When you try to start the RoleTailored client, you see the following message:

Cannot connect the Change Listener to SQL Server.

This topic provides guidelines for determining if you must enable the Object Change Listener on the computer running Microsoft Dynamics NAV Server. It also provides instructions for enabling the Object Change Listener in SQL Server Management Studio and instructions for enabling query notification for the Object Change Listener, which is an optional step that can help improve performance.

Determining If You Must Enable the Object Change Listener

For certain installation configurations, you must manually enable the Object Change Listener. The following table explains the configuration options.

Account choice Microsoft Dynamics NAV Server and database on same computer Microsoft Dynamics NAV Server and database on different computers

Network Service account

No Object Change Listener additional configuration is required unless you attach databases manually.

  • Object Change Listener configuration is required.

  • In the following procedures, specify YourDomain\YourMachineName$ for ReplaceWithNAVSrvrAcct.

Domain user account

  • Object Change Listener configuration is required.

  • In the following procedures, specify the domain user account for ReplaceWithNAVSrvrAcct.

  • Object Change Listener configuration is required.

  • In the following procedures, specify the domain user account for ReplaceWithNAVSrvrAcct.

Enabling the Object Change Listener

To enable the Object Change Listener, follow these steps:

To enable and assign minimum permissions for the Object Change Listener

  1. Open SQL Server Management Studio. and then connect to your SQL Server instance.

  2. On the File menu, point to New, and then click Query with Current Connection.

  3. Type the following SQL statements.

    CopyCode image Copy Code
    USE MASTER
CREATE LOGIN [ReplaceWithNAVServerAccount] FROM WINDOWS;
GO

  4. Highlight the lines that you typed and, on the Query menu, click Execute.

  5. Now type these lines below the existing lines.

    CopyCode image Copy Code
    USE [ReplaceWithYourDatabaseName]
CREATE USER [ReplaceWithNAVServerAccount] FOR LOGIN [ReplaceWithNAVServerAccount];

  6. Highlight the lines that you just typed and, on the Query menu, click Execute.

  7. Now type these lines below the existing lines.

    CopyCode image Copy Code
    CREATE SCHEMA [$ndo$navlistener] AUTHORIZATION [ReplaceWithNAVServerAccount];
GO

  8. Highlight the lines that you just typed and, on the Query menu, click Execute.

    It's very possible that you will see an error stating that the schema in question already exists. This is not a problem.

  9. Now type these lines below the existing lines.

    CopyCode image Copy Code
    ALTER USER [ReplaceWithNAVServerAccount] WITH DEFAULT_SCHEMA = [$ndo$navlistener];
GRANT SELECT ON [Object Tracking] TO [ReplaceWithNAVServerAccount];
GO

  10. Highlight the lines that you just typed and, on the Query menu, click Execute.

    Note Note

    The Object Tracking table name may be in a different language than English. If it is, then replace "Object Tracking" with the actual table name from your database.

  11. On the Query menu, click Execute.

Enabling Query Notification for the Object Change Listener

Enabling query notifications is not required but can improve performance when the Object Change Listener is listening for changes.

To enable query notification for the Object Change Listener

  1. Open SQL Server Management Studio.

  2. On the File menu, point to New, and then click Query with Current Connection.

  3. Type the following SQL statements:

    CopyCode image Copy Code
    ALTER DATABASE [ReplaceWithYourDatabaseName] SET ENABLE_BROKER;
GRANT CREATE PROCEDURE TO [ReplaceWithNAVSrvrAcct];
GRANT CREATE QUEUE TO [ReplaceWithNAVSrvrAcct];
GRANT CREATE SERVICE TO [ReplaceWithNAVSrvrAcct];
GRANT VIEW DEFINITION TO [ReplaceWithNAVSrvrAcct];
GRANT SUBSCRIBE QUERY NOTIFICATIONS TO [ReplaceWithNAVSrvrAcct];
GRANT RECEIVE ON QueryNotificationErrorsQueue TO [ReplaceWithNAVSrvrAcct];
GRANT REFERENCES ON CONTRACT::[http://schemas.microsoft.com/SQL/Notifications/PostQueryNotification] TO [ReplaceWithNAVSrvrAcct];
GO

  4. On the Query menu, click Execute.

See Also

Concepts

Installation Considerations for Microsoft SQL Server


Troubleshooting SQL Server Connection Problems

Troubleshooting SQL Server Connection Problems

After installing and configuring Microsoft Dynamics NAV 2009 software, you may not be able to connect the RoleTailored client to Microsoft Dynamics NAV Server. The following error message appears when you attempt to start the RoleTailored client.

The program could not create a connection to the server. Do you want to try again?

This topic describes configuration changes that you can try to resolve SQL Server connection problems.

Enable Protocols in SQL Server Configuration Manager

SQL Server Configuration Manager is a tool for managing SQL Server services and network connectivity. You can use SQL Server Configuration Manager to enable and disable network protocols. For Microsoft Dynamics NAV to work correctly, the Named Pipes and TCP/IP protocols must be enabled for SQL Server.

Follow these steps to verify that these protocols are enabled or to enable them if they are currently disabled.

To enable Named Pipes and TCP/IP in SQL Server

  1. Start SQL Server Configuration Manager

  2. Expand the SQL Server Network Configuration node in the tree view, and then click Protocols for MSSQLSERVER.

  3. Under Protocol Name in the right pane, verify that Named Pipes and TCP/IP have the status Enabled.

  4. If either protocol is not enabled, right-click the protocol, and then click Enable.

After exiting SQL Server Configuration Manager, start the RoleTailored client again to see if the connection problem has been resolved.

Allowing SQL Server with Windows Firewall

If Windows Firewall is running on the computer running SQL Server, then you must explicitly specify the SQL Server executable file as an allowed exception before you can connect to the Microsoft Dynamics NAV database with the Classic client.

To allow SQL Server with Windows Firewall

  1. In Windows Server 2003, in Control Panel, open Windows Firewall, and then click the Exceptions tab.

    -or-

    In Windows Server 2008, in Control Panel, open Windows Firewall, click Change settings, and then click the Exceptions tab.

  2. Click Add program.

  3. Click Browse, and then browse to the location of the SQL Server executable file (sqlservr.exe). The default location on a computer running Windows Server 2003 is:

    CopyCode image Copy Code
    Program Files\Microsoft SQL Server\MSSQL.1\MSSQL\Binn\sqlservr.exe

  4. Double-click the executable file to select it and to exit the Browse window, and then click OK to close the Add a Program window.

  5. Click OK to close Windows Firewall.

After exiting SQL Server Configuration Manager, start the RoleTailored client again to see if the connection problem has been resolved.

See Also

Tasks

Walkthrough: Installing the Three Tiers on Three Computers

Concepts

Configuring Microsoft SQL Server
Installation Considerations for Microsoft SQL Server


Configuring Application Server

Configuring Application Server

Application Server is a component of the Classic Architecture in Microsoft Dynamics NAV 2009.

While you run Microsoft Dynamics NAV 2009 Setup, you can provide configuration information for Application Server.

Configuring Application Server in Setup

You can configure Application Server while running Microsoft Dynamics NAV 2009 Setup. You must first select the Application Server as a component to install. To do this, select the installation option that includes the NAV Server: the Classic Server Components Option. For more information, see Installation Options.

You can also customize your installation and customize the list of components to install. For more information, see How to: Choose Components to Install.

After you choose the Classic Server Components option, or customize your component list to include Application Server, the Specify parameters pane is displayed in Setup. Click Application Server (the underscore indicates that this component is configurable) to open an Installation Parameters pane.

Settings

The list of parameters that you see in the Specify parameters pane varies, depending on which components you have selected for configuration. The following parameters pertain to Application Server.

Parameter | Description
Service name | Specifies the service name for the Classic Database Server that Application Server connects to.
Service name SQL | Specifies the service name for the SQL Server database server that Application Server connects to.

Click Apply when you have finished entering values to return to the Specify parameters pane in Setup.

Only one of these parameters is meaningful, depending on which type of database server Application Server connects to. Use Application Server Manager (described below) to specify whether Application Server connects to a Classic database server or an SQL Server database server.

Configuring Application Server After Installing

After you install Application Server, use Application Server Manager to modify its properties. With Application Server Manager you can modify the two properties that you configured with Setup, or any additional properties.

Configuration information about Application Server is available in w1w1atas.pdf ("Installation & System Management: Application Server for Microsoft Dynamics NAV"). To obtain this manual, go to Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download w1w1atas.pdf.

See Also

Concepts

Classic Server Components Option Requirements


Configuring Classic Database Server

Configuring Classic Database Server

The Classic Database Server is a component of the Classic Architecture in Microsoft Dynamics NAV 2009.

Note Note

The Classic database service does not interact with RoleTailored Architecture components.

While you run Microsoft Dynamics NAV 2009 Setup, you can provide configuration information for the Classic Database Server.

Configuring Classic Database Server in Setup

You can configure the Classic Database Server while running Microsoft Dynamics NAV 2009 Setup. You must first select the Classic Database Server as a component to install. To do this, select the installation option that includes the NAV Server: the Classic Server Components Option. For more information, see Installation Options.

You can also customize your installation and customize the list of components to install. For more information, see How to: Choose Components to Install.

After you choose the Classic Server Components option, or customize your component list to include Classic Database Server, the Specify parameters pane is displayed in Setup. Click Database Server (the underscore indicates that this component is configurable) to open an Installation Parameters pane.

Settings

The list of parameters that you see in the Specify parameters pane varies, depending on which components you have selected for configuration. The following parameters pertain to the Classic Database Server.

Parameter | Description
Server Name | Specifies the name of the database server. The default value is the computer name.
Network Protocol | Specifies the network protocol for communication between clients and the database server. Default: TCP/IP (Kerberos) This is the secure version of TCP/IP, with Kerberos authentication. Additional values: TCP/IP, NetBIOS
Cache size | Specifies the size of the database server cache (in KB). Default: 10000
Commit cache | Specifies whether to allow clients to write to the cache, instead of directly to the database. This can increase write performance. Default: Yes

Click Apply when you have finished entering values to return to the Specify parameters pane in Setup.

Configuring Classic Database Server After Installing

After you install Classic Database Server, use Database Server Manager, a Microsoft Management Console snap-in, to modify its properties. With Database Server Manager you can modify any of the properties that you configured with Setup, or any additional properties.

Note Note

It is always necessary to activate a license file using the Classic client after installing Classic Database Server. For more information, see How to: Activate the License File.

For information about how to run Database Server Manager, and for information about additional configuration options, see w1w1ism.pdf ("Installation & System Management: C/SIDE Database Server for Microsoft Dynamics NAV"). To obtain this manual, go to Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download download w1w1ism.pdf.

See Also

Concepts

Classic Server Components Option Requirements


Configuring Automated Data Capture System

Configuring Automated Data Capture System

The Automated Data Capture System (ADCS) is a Microsoft Dynamics NAV tool that gives companies the ability to accurately capture data for inbound, outbound, and internal documents, primarily in connection with warehouse activities. With ADCS, company employees use handheld devices and radio frequency technology to continuously validate warehouse inventories.

ADCS requires Classic Application Server, a component of the Classic Architecture in Microsoft Dynamics NAV 2009.

While you run Microsoft Dynamics NAV 2009 Setup, you can provide configuration information for ADCS.

Configuring ADCS in Setup

You can configure ADCS while running Microsoft Dynamics NAV 2009 Setup. You must first select the ADCS as a component to install. To do this, you need to customize the list of components to install to include ADCS, which is not included in any of the predefined Installation Options. For more information, see How to: Choose Components to Install.

After you customize your component list to include ADCS, the Specify parameters pane is displayed in Setup. Click Automated Data Capture System (the underscore indicates that this component is configurable) to open an Installation Parameters pane.

Settings

The list of parameters that you see in the Specify parameters pane varies, depending on which components you have selected for configuration. The following parameters pertain to ADCS.

Parameter | Description
Server IP Address | Specifies the IP Address for Application Server. Default: 127.0.0.1
TCP Port | Specifies the port to use for connecting to Application Server. Default: 11322

Click Apply when you have finished entering values to return to the Specify parameters pane in Setup.

Configuring ADCS After Installing

See w1w1InstADCS.pdf ("Automated Data Capture Systems for Microsoft Dynamics NAV") for details about additional configuration tasks you must perform to get ADCS up and running.

To obtain this manual, go to Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center and download w1w1InstADCS.

See Also

Concepts

Automated Data Capture System Requirements


How to: Configure Windows Services

How to: Configure Windows Services

Some Microsoft Dynamics NAV 2009 components are Windows services: processes that remain in memory, function without user intervention, and serve other processes as needed.

Windows services must log on to an account to access resources and objects on the operating system. If all your Microsoft Dynamics NAV components run on a single computer you do not need to configure Windows services. If you have installed different components on different computers, then you may need to configure one or more services to be able to communicate with other Microsoft Dynamics NAV 2009 components.

The following components run as Windows services:

  • Microsoft Dynamics NAV Server

    The NAV Server logs on using the NT Authority\Network Service account by default. If the NAV Server and SQL Server are on different computers, Microsoft recommends that you configure the NAV Server to log on using a dedicated Windows domain user account. This account should not be an administrator either in the domain or on any local computer.

  • Classic Application Server

    The Application Server also uses the NT Authority\Network Service account by default. If Application Server and the database server (either SQL Server or the Classic Database Server) are on different computers, Microsoft recommends that you configure the Application Server to log on using a dedicated Windows domain user account that is recognized by the database server service. This account should not be an administrator either in the domain or on any local computer.

  • SQL Server (MSSQLSERVER)

    Microsoft Dynamics NAV 2009 Setup does not install the SQL Server service, though it will install the SQL Server Express service (SQLEXPRESS) if you use Setup to install the Demo Install Option or to install the Database Components Option on a computer where SQL Server is not already installed.

    The SQL Server service uses the Local System account by default. We recommend that you use a local user or domain user account instead.

    Note Note

    To configure the MSSQLSERVER service, you should use SQL Server Configuration Manager instead of the Control Panel Services tool, as described below. Using SQL Server Configuration Manager assures that additional permissions required for the SQL Server service account are granted. The procedure is essentially the same: select the MSSQLSERVER service and navigate to the Log On tab.

Configuring a Service

The following procedure assumes a Server operating system (Windows Server 2003 or 2008). For Windows XP or Windows Vista, the steps are slightly different but the process is essentially the same.

Configuring a service

  1. In Control Panel, click Administrative Tools, and then click Services.

  2. In the list of services, double-click the service that you want to configure.

  3. In the Server Properties dialog box, go to the Log On tab.

  4. Select This account and either enter or browse to the account that you want the service to use.

  5. Enter and confirm the password for this account.

  6. Click OK to exit the Server Properties dialog box.

See Also

Tasks

Walkthrough: Accessing Multiple Microsoft Dynamics NAV Databases from a Single Microsoft Dynamics NAV Server Computer


How to: Add Users

How to: Add Users

Microsoft Dynamics NAV supports user-level security to ensure that only persons with the appropriate authorization can access information in the system. You must add users and assign roles so that each person is able to perform tasks in accordance with the permissions that they have been allocated.

Microsoft Dynamics NAV supports two methods for logging on:

  • Database Server Authentication

  • Windows Authentication

The RoleTailored client requires Windows authentication and does not support Database authentication.

All administration of security and permissions is performed through the Classic client and not the RoleTailored client.

Note Note

To add users on a computer running Windows Vista with User Access Control enabled, start the Classic client with administrator privileges. To do this, right-click Microsoft Dynamics NAV Classic with Microsoft SQL Server in the Start menu, and then select Run as administrator.

For additional information about administering users and roles, see the section Security and Permissions in the Classic client online Help.

Adding and Synchronizing Users

To add users using Windows Authentication

  1. Open Microsoft Dynamics NAV Classic with SQL Server.

    This opens the Classic client. If you have not already installed the Classic client, see How to: Install Classic Client for Administrative Tasks.

  2. From the Tools menu, click Security, and then click Windows Logins.

  3. Click in an empty row and type the user's login in the format TheirDomain\TheirUserName, and press TAB to add the user.

  4. Select the user and click Roles.

  5. Select an appropriate RoleID, press TAB to commit the information, and then close the form.

  6. From the Tools menu, click Security, and then click Synchronize All Logins.

See Also

Other Resources

Installation Walkthroughs


Walkthrough: Setting Up Document Approvals

Walkthrough: Setting Up Document Approvals

The document approvals feature enables companies to automate the process of requesting approvals on documents like sales or purchase orders. When you set up document approvals, you establish an approver for each user, and you can also set a substitute approver. You set the sales, purchase, and request limits per user, so that when users create a document above their limits, they are prompted to send an approval request. Approval requests and other notifications are sent using a Simple Mail Transfer Protocol (SMTP) server. You must set up notifications so that approvers are alerted when they have a document waiting for approval.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Setting up two users with Windows Authentication log on credentials.

  • Applying document approval settings for the two users.

  • Setting up e-mail notification.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 Demo installed. For more information, see Demo Install Option.

  • Two users with permission to work in the CRONUS International database. For more information, see How to: Create Users in the installation and configuration Help.

  • SMTP server that you and the second user you create are members of.

Expand image Story

Sean is a power user at CRONUS International Ltd. CRONUS has several departments that handle documents, including Sales and Purchasing. Sean has been asked to set up document approvals to automate the process of requesting an approval. He decides to test the approval process on a single machine before setting it up for CRONUS employees. He creates two users with Windows Authentication log on credentials. He then sets approval limits for the users and designates the templates to be used for approvals. Finally, he sets up notifications to alert users when an approval is ready for consideration.

Expand image Setting Up the Sample Data

Sean adds an additional user with Windows Authentication log on credentials.

Note Note

To perform the procedures in this walkthrough, you can create a second user with a computer log on, rather than a domain log on.

To add a second computer user

  1. On your computer, locate the Local Users and Groups console tree.

    If you are working on a machine with Microsoft Windows Vista installed, you may need to open the Microsoft Management Console, and add the Local Users and Groups snap-in.

    If you are working on a machine with Microsoft Windows Server installed, you can open Computer Management, and then expand System Tools.

  2. Expand Local Users and Groups, right-click the Users folder, and on the shortcut menu, click Add User.

  3. Add the log on information for the second user. Be sure that you clear the User must change password at next logon check box.

After he has created a second user, Sean must add the user to the Microsoft Dynamics NAV Server database. This is a task that is performed in the Classic client, where security settings are established even if the setup is for working in the RoleTailored client.

To add your second user to Microsoft Dynamics NAV

  1. In the Classic client for Microsoft Dynamics NAV 2009 with Microsoft SQL Server, click Tools, point to Security, and then click Windows Logins.

  2. In the Windows Logins window, on an empty row, type the user's login in the format UserDomain\UserName. Press TAB to add the user.

  3. Select the new user, and click Roles.

  4. In the Roles window, in the Role ID column, select Super.

  5. Close the Roles window and the Windows Login window.

  6. On the Tools menu, point to Security, and then click Synchronize All Logins.

    To ensure that the new user has been properly added to the CRONUS demo database, you can use Microsoft SQL Server Management Studio to view the list of users added to the database. You may also want to log as the new user in Microsoft Dynamics NAV.

Expand image Applying Document Approval Settings for Users

When he has confirmed that his second user has been added to the database, Sean switches to the RoleTailored client. He adds himself as a salesperson, because he will approve documents sent by the additional user he created. Sean sets himself as the approver, and sets sales and purchase limits that require approval for the user he created previously.

To set up document approvals users

  1. In the RoleTailored client, click Departments, click Sales and Marketing, and then click Sales.

  2. Click Salespeople, and then click New.

  3. In the Code box, add your initials, and in the Name box, type your name.

  4. Click Departments, click Application Setup, and then click Document Approval.

  5. Click Approval Setup, and in the Approval Setup window, click User Setup.

  6. Click New, and then in the Approval User Setup window, select the User ID for yourself.

  7. Complete the user setup with the information in the User 2 column in the following table. Then, use the information in the User 1 column to set up the user you created.

Note Note

You must set up an approver before you can set up users who require that approver's approval. Therefore, you set up User 2, who acts as the approver in this scenario, before you set up User 1.

Approval Settings | User 1 | User 2 (you)
User ID | Provide the user ID you assigned this user | Provide the user ID you assigned this user
Salespers./Purch. Code | User 2 |
Approver ID | User 2 |
Sales Amount Approval Limit | 5000 | Select the Unlimited check box
Purchase Amount Approval Limit | 5000 | Select the Unlimited check box
Request Amount Approval Limit | 5000 | Select the Unlimited check box
E-mail | User 1 e-mail address | User 2 e-mail address

Expand image Setting Up Notifications

Sean applies notification settings to ensure he is notified when an approval is ready. He sets Microsoft Dynamics NAV to automatically request a comment when a user rejects an approval request. Finally, he completes the SMTP mail setup, so that mail will be sent when an approval request is sent.

To set up e-mail notification

  1. In the Approval Setup window, on the Approval Administrator drop-down list, select your User ID.

  2. Select the Request Rejection Comment check box.

  3. Expand the Notification FastTab, and in the Notify User About list, select all four check boxes.

  4. Click OK, and then open the Approval Templates page.

  5. Double-click a line, and select the Enabled check box for the P-Order and the S-Order.

To set up SMTP mail

  1. Click Departments, click IT Administration, click General, and then click SMTP Mail Setup.

  2. In the SMTP Server text box, type the name of your SMTP server.

  3. In the Authentication box, select Basic.

  4. Add the user ID and password for your SMTP server.

    This is generally the administrator ID and password for the SMTP server that you and your second user are registered on. You can also use Anonymous authentication.

Expand image Next Steps

When you have completed the document approvals setup, you can try sending and approving, rejecting, or delegating approval requests. For more information, see "Walkthrough: Approving Documents," in the Microsoft Dynamics NAV 2009 online Help.


How To: Set Up Delegation

How To: Set Up Delegation

When the RoleTailored client, Microsoft Dynamics NAV Server, and SQL Server are installed on separate computers, the client interacts with the database through an intermediate computer, which is running Microsoft Dynamics NAV Server. The server is performing actions on the client's behalf. This process is known as impersonation.

Delegation is when a front-end service forwards a client request to a back-end service so that the back-end service can also impersonate the client. Impersonation is typically used to check whether a client is authorized to perform a particular action, while delegation is a way of flowing impersonation capabilities, along with the client’s identity, to a back-end service. You can use delegation as a Windows domain feature with Kerberos-based authentication.

As a domain administrator, you must perform the following tasks to enable delegation within the three-tier RoleTailored architecture for configurations where the RoleTailored client, Microsoft Dynamics NAV Server, and SQL Server are on separate computers:

  1. Creating service principal names

  2. Delegating access to the SQL Server service

    Note Note

    When the RoleTailored client and Microsoft Dynamics NAV Server are on different computers, file operations that are initiated from the RoleTailored client, such as RENAME and COPY, fail if the destination for the file operation is not on the computer running Microsoft Dynamics NAV Server. One solution is to configure Microsoft Dynamics NAV Server to delegate on behalf of the RoleTailored client as described in this topic. In this case, you may also need to configure Microsoft Dynamics NAV Server to delegate to the cifs service on the destination computer. To avoid this complication entirely, define file operations so that the destination is always on the computer running Microsoft Dynamics NAV Server. You can then use a shared folder on the computer running Microsoft Dynamics NAV Server and share it with all users who require access to the files.

    Note Note

    If your implementation is not working as expected after following the instructions in this topic, then you can use the Best Practices Analyzer for Microsoft Dynamics NAV 2009 (requires PartnerSource login). Install this diagnostic tool on your computer running Microsoft Dynamics NAV Server to help identify configuration issues that may be preventing your three-tier deployment of Microsoft Dynamics NAV from working correctly.

Creating Service Principal Names

The first step in setting up delegation is to create any necessary service principal names (SPN). To make delegation more secure, Active Directory uses Kerberos to authenticate services. An SPN is the name by which a client uniquely identifies an instance of a service, using the account under which the service runs. To make delegation work, you must explicitly create an SPN when either the Microsoft Dynamics NAV Server service or the SQL Server service is running under a dedicated domain user account. We recommend using a dedicated domain user account for the highest security.

Note Note

You must have the setspn command-line tool installed on your server. In Windows Server 2008, the setspn tool is included if you have installed the Active Directory Domain Services server role. In Windows Server 2003, you must download the Windows Server 2003 Service Pack 2 32-bit Support Tools to get the setspn tool.

To create a service principal name

  1. Open an elevated command prompt. Click Start, and in the search window, type Command Prompt.

  2. Right-click Command Prompt, and then click Run as administrator.

  3. At the command prompt, create the SPN. The syntax is:

    CopyCode image Copy Code
    setspn -A InstanceName/FullyQualifiedDomainNameOfServer:Port Domain \User

    See Walkthrough: Installing the Three Tiers on Three Computers for an example of how to create SPNs when deploying Microsoft Dynamics NAV.

Delegating Access to the SQL Server Service

Configuring delegation means explicitly configuring the Microsoft Dynamics NAV Server service to delegate its access to the database server on behalf of the RoleTailored client. To make the access more secure, you specify delegation to a specific service on a specific server.

To delegate access to the SQL Server service

  1. On any server computer in the domain, click Start, and then click Run.

  2. In the Open field, type dsa.msc.

    This opens the Active Directory Users and Computers utility.

  3. To configure delegation, the functional level for the domain must be Windows Server 2003 or higher. To verify the domain functional level, right-click the node for the domain where you have installed Microsoft Dynamics NAV, and then click Raise Domain Functional Level. If the level is not at least Windows Server 2003, then raise it to that level.

  4. Right-click the node for the domain where you have installed Microsoft Dynamics NAV, and then click Find.

  5. In the Find Users, Contacts, and Group dialog box, type the name of the domain user in the Name field, and then press ENTER.

  6. In the Search results area, right-click the domain user, and then click Properties.

  7. On the Delegation tab, click Trust this user for delegation to specified services only, and then click Use Kerberos only.

  8. Click Add to open the Add Services dialog box.

  9. In the Add Services window, click Users or Computers, and then type the name of the domain user.

  10. In the list of services for the domain user, click MSSQLSvc, which is the name of the SQL Server service.

  11. Click OK to exit the Add Services dialog box.

  12. Click OK to close all open dialog boxes.

See Also

Tasks

Walkthrough: Installing the Three Tiers on Three Computers


Troubleshooting: Microsoft Office Outlook Integration and Synchronization

Troubleshooting: Microsoft Office Outlook Integration and Synchronization
See Also
CollapseAll image

This topic lists some common problems that can arise when using the Microsoft Office Outlook Add-in.

Expand image Cleaning up Data and Configuration Information

You may need to test and try out multiple installations and configurations of the Microsoft Dynamics NAV Synchronization Add-in.

To ensure that you are starting from a clean installation, you should delete the following files from your computer before starting a new setup:

  • Microsoft Dynamics NAV 2009 —Storage of what has been synchronized and setup in the add-in: C:\Users\<user name>\AppData\Local\Isolated storage.

  • Microsoft Dynamics NAV 2009, SP1 — Storage of what has been synchronized and setup in the add-in:C:\Users\<user name>\AppData\Local\Microsoft Dynamics NAV\OutlookSynch\settings.xml

  • RoleTailored client setup: C:\Users\<user name>\AppData\Roaming\Microsoft\Microsoft Dynamics NAV\personalizationStore.xml.

Expand image Verifying the Change Log Setup

By default, the change log is activated. However, you may want to verify that the activation is valid. An example of when you may need to do this is when no Contacts or To-Dos are synchronized when Outlook Synchronization is run.

To verify the Change Log Setup setting

  1. In the navigation pane, click Departments, click Administration, click IT Administration, click General, and then click Change Log Setup.

  2. Verify that the Change Log Activated is selected.

  3. To validate specific Change Log Setup settings, in the Edit Change Log Setup window, click Related Information, point to Setup, and then click Tables.

  4. The default change log setup contains information for the Salesperson/Purchaser, Contact, and To-do tables. You can make additional modifications.

Expand image Running Microsoft.Dynamics.NAV.OLSync.OLSyncSupplier.OutlookObjectLibrary

You may receive the following message when setting up Outlook integration with Microsoft Dynamics NAV:

The server has requested to run Microsoft.Dynamics.NAV.OLSync.OLSyncSupplier.OutlookObjectLibrary on your client.

To complete installation of the Microsoft Dynamics NAV Synchronization Add-in, select the Always Allow option.

Expand image Setting Conditions

Setting conditions for the TASK and APP entities is required. Meetings and tasks need a Meeting Organizer or Task Owner, so you must create a condition.

To configure conditions

  1. In the navigation pane, click Departments, click Administration, click Application Setup, click Microsoft Outlook Integration, and then click Outlook Synch. User Setup.

  2. Select the line with the APP entity, and then click in the Condition field.

  3. In the Outlook Synch. Filters -Condition window, in the Field Name field, select Salesperson Code. In the Value field, add the code for the salesperson.

  4. Repeat these steps for the TASK entity.

Otherwise, setting conditions is not mandatory, but you should do it to prevent mass data transfer to a local mailbox or a Public Folder. In large environments with hundreds of contacts, it may be necessary to set conditions to limit the data that is to be synchronized to every salesperson who has a mailbox that is configured for Outlook synchronization.

If there are no conditions set for the contacts entities, then you may get a message to look at the debug log. This is due to a security setting on the Exchange Server. If a large set of data is synchronized to Exchange Server (first trigger is set to 250 objects), then Exchange Server logs an error in the event log file and does not allow you to add the data to the mailbox:

Closing Mapi session "/o=First Organization/ou=First Administrative Group/cn=Recipients/cn=XY" because it exceeded the maximum of 250 objects of type "objtMessage

To work around this limitation, you can adjust the registry based on the objects that can be found in the 9646 event ID in the application event log file on the Exchange Server. Once you have completed setting conditions, you may need to register the changes in the change log, but only if you have made changes to the default configuration in the Outlook Synch. Entities window. The changes are registered in the following order in the change log: CONT_SP, CONT_COMP, CONT_PERS, TASK, and APP entity.

For more information, see the following articles:

  • Knowledge Base article 830836: Event ID 9646 is logged when you try to send many messages in Exchange Server 2003

  • Knowledge Base article 830829: Your Exchange Server 2003 computer may stop responding after a MAPI client opens more than the default value of certain server objects

  • An Exchange 2007 server stops responding to a MAPI client and logs event ID 9646 in the Application log

    Note Note

    There is no debug log by default. You must enable it first. For more information, see Knowledge Base article 944237: How to enable the log file mode for the Outlook Synchronization feature in Microsoft Dynamics NAV 5.0 (requires PartnerSource login).

Expand image Locating the Error Log Created by the Outlook Synchronization Process

You may receive the following message:

An Error has occurred during the synchronization process. You can find the error details in the log file

The location of this log file depends on the operating system that you are using. You can find the path to the file by looking in the Outlook.exe.config file: c:\Program Files\Microsoft Office\Office<version number 11 or 12>\Outlook.exe.config.

Note Note

The amount of information that is logged in the log file can be changed to show more detailed information by modifying the Outlook.exe.config file. For more information, see Knowledge Base article 944237: How to enable the log file mode for the Outlook Synchronization feature in Microsoft Dynamics NAV 5.0 (requires PartnerSource login).

Expand image Synchronizing Large Sets of Data

Synchronizing large amounts of data may cause issues with the connection through the application server and Web services.

The application server may time out if the amount of data is too large. One way to allow a full synchronization is to change the timeout setting in the Outlook.exe configuration file: c:\Program Files\Microsoft Office\Office<version number 11 or 12>\Outlook.exe.config.

CopyCode image Copy Code
<add key="SynchronizationTimeOutSec" value="120"></add>

If you are synchronizing using the Web services connection, the maximum size of the Web service can be changed. You can configure the maximum permitted size of a Web Services request in the CustomSettings.config file.

CopyCode image Copy Code
<!--  Maximum permitted size of a Web Services request, in kilobytes-->
<add key="WebServicesMaxMsgSize" value="512"></add>

However, you should not regularly synchronize large sets of data, although it may be appropriate to do so during initial setup. Instead, we recommend that you change the Web service size back to an appropriate level after a full synchronization.

Expand image Setting up Microsoft Outlook Integration in a Three-Machine Environment

When selecting a company, you may receive a message that is similar to one of the following messages:

  • The connection to "" Microsoft Dynamics NAV database failed. The program returned the following error: GetCompaniesList error: The login failed when connecting to SQL Server <DatabaseTier>. connection string: NavSynchronizationUrl=http://<ServiceTier>:7047/DynamicsNAV/WS/Codeunit/DynamicsNAVsynchOutlook;CompanyName=<CompanyName>; Please verify your synchronization settings. If the problem persists contact your system administrator.

  • The connection to "" Microsoft Dynamics NAV database failed. The program returned the following error:GetCompaniesList error: The request failed with HTTP status 401: Unauthorized. connection string: NavSynchronizationUrl=http://<ServiceTier>:7047/DynamicsNAV/WS/Codeunit/DynamicsNAVsynchOutlook;CompanyName=<CompanyName>; Please verify your synchronization settings. If the problem persists contact your system administrator.

In the message, <DatabaseTier> is the server name of the SQL Server, <ServiceTier> is the server name of the Microsoft Dynamics NAV Server, and <CompanyName> is the company name.

These errors can occur if Microsoft Dynamics NAV Web services are not set up with the correct SPNs and delegation information. They can also occur if the Web Service path is not set correctly in the Connection tab. For more information, see Walkthrough: Installing the Three Tiers on Three Computers. Also see the following blog post: NAV 2009 Web Services on a three machine setup.

Expand image Configuring the Outlook Profile in an Environment Other Than Microsoft Exchange

When you add and configure a new user Outlook profile in an environment other than Microsoft Exchange and are working with the TASK entity, ensure that the name of the Active Directory user (Full name) or name of the Mailbox owner matches the Salesperson as configured on the Salesperson/Purchaser card.

Otherwise, you may receive this message:

The error occurred while setting the Owner property of the item: Task owner can be set to XXX only

Expand image Displaying the Microsoft Dynamics NAV Synchronization Toolbar

After you reinstall the Microsoft Office Outlook Add-in, the Microsoft Dynamics NAV Synchronization toolbar may not appear in Outlook, even though the toolbar is selected in the list of available toolbars from the View menu. This happens because the previous version of the add-in was still running during reinstallation.

To display the Microsoft Dynamics NAV Synchronization toolbar

  1. In Outlook, on the Tools menu, click Trust Center, click Add-ins, and then select the Apply macro security settings to installed add-ins check box.

  2. In the Manage box, verify that COM Add-ins is selected, and then click Go.

  3. If the Microsoft Dynamics NAV Synchronization Add-in is selected, clear the check box and click OK.

  4. On the Tools menu, click Trust Center, click Add-ins, and then clear the Apply macro security settings to installed add-ins check box.

  5. In the Manage box, verify that COM Add-ins is selected, and then click Go.

  6. Select the Microsoft Dynamics NAV Synchronization Add-in check box, and then click OK.

Expand image Showing Synchronization

We recommend that you enable the Show Synchronization Progress option in Outlook so that a user knows when synchronization is taking place. This helps a user avoid getting an error because of the user closing Outlook when synchronization is occurring.

To set rules for synchronization

  1. In Outlook, on the Microsoft Dynamics NAV Synchronization toolbar, click Settings.

  2. On the General tab, select Show synchronization progress and Show synchronization summary.

Expand image Configuring Microsoft Dynamics NAV Synchronization Add-in on Localized Versions of Microsoft Dynamics NAV

When you use localized versions of Microsoft Dynamics NAV, there are additional strategies that you must take to ensure successful implementation of the Microsoft Outlook integration. You must log on as the dedicated user account that is configured for the NAS service and configure the computer's regional options to match the language of the Classic client.

Aligning System Text Files and License Files

When you use a localized version of Microsoft Dynamics NAV, some actions are required to align the version and country codes that are specified in the license (.flf) and system text (.stx) files of the Classic client, Application Server, and Outlook Add-in with the localization that is being used.

Note Important

When you install Outlook Synchronization Update, the described alignment must be performed only after you have imported and compiled the Outlook Synchronization Update objects.

For details on installing the Outlook Synchronization Update, see the (requires PartnerSource login). In the appendix, see "Installing Outlook Synchronization Update."

After you have installed the Classic Client, Application Server, and Outlook Add-in, the .flf and .stx files have the following version and country codes. The table is based on the example of installing Microsoft Dynamics 2009 for Germany.

 | Cronus.flf | fin.flf | fin.stx
Classic | DE | Not applicable | Version W1, Country Code DE
Classic\DEU | Not applicable | Not applicable | Version DE, Country Code DE
Application Server | W1 | Not applicable | Version W1, Country Code W1
OutlookAddin | Not applicable | W1 | Version W1, Country Code W1

To align the version and country codes that are specified in the license (.flf) and system text (.stx) files with the localization used

  1. Copy fin.stx from the Classic\<language code> folder to the Application Server and OutlookAddin folders.

  2. Copy Cronus.flf from the Classic folder to the Application Server folder.

  3. Copy Cronus.flf from the Classic folder to the OutlookAddin folder.

  4. In the OutlookAddin folder, delete the fin.flf file.

With these changes, the correct license and system text files are located as follows:

 | Cronus.flf | fin.flf | fin.stx
Classic | DE | Not applicable | Version W1, Country Code DE
Classic\DEU | Not applicable | Not applicable | Version DE, Country Code DE
Application Server | DE | Not applicable | Version DE, Country Code DE
OutlookAddin | DE | Not applicable | Version DE, Country Code DE

Configuring the User with the Required Outlook Synch Entities

Next, to continue configuration of Outlook Synch User Setup, check the APP and TASK entities in a localized release of Microsoft Dynamics NAV 2009, because the Links value under Outlook Collection may contain a translated value, such as “Koppelingen” in the Dutch version of Microsoft Dynamics NAV 2009. This value must be updated.

To configure the Outlook Collections correctly for the TASK and APP entity

  1. Click Administration, click Application Setup, click Microsoft Office Outlook Integration, and then click Outlook Synch. Entities.

  2. Double-click the APP entity to open it for editing.

  3. Select the field with the translated value for “Links,” and then open it.

  4. In Outlook Synch. Lookup Names, select Links, and then click OK.

  5. Double-click the TASK entity to open it for editing.

  6. Select the field with the translated value for “Links,” and then open it.

  7. In the Outlook Synch. Lookup Names window, select Links, and then click OK.

Expand image Finding Additional Information

For additional information on the setup and configuration of the Microsoft Dynamics Synchronization Add-in, see the product Help. You can search for the topic "Set Up Outlook Synchronization" as a starting point. In addition, you can see the Outlook Integration Installation & Setup Technical White Paper (requires PartnerSource login). Although the paper describes installation for Microsoft Dynamics NAV 5.0, much of the information applies to Microsoft Dynamics NAV 2009. Last, you can also find troubleshooting advice in the following blog: NAV Developer's Blog.

Expand image See Also

Tasks

Walkthrough: Setting Up Outlook Synchronization
Walkthrough: Synchronizing Information Between Outlook and Microsoft Dynamics NAV

Other Resources

Installation Options


How to: Install Language Modules in Microsoft Dynamics NAV 2009 SP1

How to: Install Language Modules in Microsoft Dynamics NAV 2009 SP1

The topic describes how to install language modules in Microsoft Dynamics NAV 2009 SP1. For more information about how to install language modules in the original version of Microsoft Dynamics NAV 2009, see Language Modules for Microsoft Dynamics NAV 2009 (requires PartnerSource login).

To install language modules in Microsoft Dynamics NAV 2009 SP1, you must first download the language module from Language Modules for Microsoft Dynamics NAV 2009 SP1 (requires PartnerSource login), and then you install the following different components separately:

  • Server component

  • RoleTailored client component

  • Classic client component

  • (optional) Microsoft Office Outlook component

  • Database component

After you install a language module, you may need to translate additional strings for customized objects in the application. For more information, see the following topics:

  • How to: Add Translated Strings By Using the Multilanguage Editor

  • How to: Add Translated Strings By Importing and Exporting Multilanguage Files

Server Component

To install the server component of a language module

  1. On the computer that is running Microsoft Dynamics NAV Server, navigate to the location where you downloaded the language module.

  2. Run the .exe file to unzip the language module files.

  3. In the Server folder, run Server.Local.<country/region code>.<language code>.msi.

  4. In Control Panel, click Administrative Tools, and then click Services to open the Services snap-in.

  5. In the list of services, right-click Microsoft Dynamics NAV Server, and then click Restart.

RoleTailored Client Component

To install the RoleTailored client component of a language module

  1. Confirm that you have installed the server component of the language module before you install the RoleTailored client component.

  2. On the computer that is running the RoleTailored client, navigate to the location where you downloaded the language module.

  3. In the RoleTailoredClient folder, run RoleTailoredClient.Local.<country/region code>.<language code>.msi.

  4. (optional) To import a localized chart for a Role Center, do the following:

    1. In the Classic client, open Object Designer.

    2. On the File menu, click Import.

    3. In the Import Objects window, browse to the location where you downloaded the language module, navigate to the RoleTailored Client folder, and then navigate to the Charts folder.

    4. Select the chart that you want to add to a Role Center, and then click Open.

      Note Note

      By default, this will overwrite an existing chart page with the same ID.

    5. Personalize a Role Center to use the chart part.

Classic Client Component

To install the Classic client component of a language module

  1. On the computer that is running the Classic client, navigate to the location where you downloaded the language module.

  2. In the ClassicClient folder, run ClassicClient.Local.<country/region code>.<language code>.msi.

  3. Install the database component of the language module by using the following procedure.

Microsoft Office Outlook Component

To install the Microsoft Office Outlook component of a language module

  1. On the computer that is running the Classic client, navigate to the location where you downloaded the language module.

  2. In the OutlookAddIn folder, run OutlookAddIn.Local.<country/region code>.<language code>.msi.

Database Component

To install the database component of a language module

  1. If you are using the Classic database, then you must expand the size of the database before you add the new language resources.

  2. Verify that the license that you are using allows you to compile objects.

  3. In the Classic client, open Object Designer.

  4. In Object Designer, click All.

  5. On the Edit menu, click Select All.

  6. On the Tools menu, point to Language Module, and then click Import.

  7. In the Language Module Import window, browse to the location where you downloaded the language module, navigate to the Database folder, select the .flm file, and then click Open.

  8. With all objects selected, on the Tools menu, click Compile.


How to: Uninstall Language Modules in Microsoft Dynamics NAV 2009 SP1

How to: Uninstall Language Modules in Microsoft Dynamics NAV 2009 SP1

To uninstall a language module, you must delete the language from the database and uninstall each component of the language module that you installed. This topic describes the steps.

For more information about how to delete translated strings from individual objects, see How to: Delete Translated Strings.

For more information about how to install language modules, see How to: Install Language Modules in Microsoft Dynamics NAV 2009 SP1.

To uninstall a language module

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, select all objects.

  3. On the Tools menu, click Language Module, and then click Export.

  4. In the Language Module Export window, in the File Name field, enter the path and file name of the file that will contain the deleted language module.

  5. In the Language field, click the AssistEdit button.

  6. In the Windows Language List window, select the language that you want to delete, and then click OK.

  7. In the Language Module Export window, select the Delete language field, and then click OK.

  8. In Control Panel, click Programs and Features.

  9. For each component of the language module that is installed, select the component, and then click Uninstall/Change.


Security in the RoleTailored Environment

Security in the RoleTailored Environment

An enterprise business solution must have a built-in security system that helps protect your database and the information that it contains from unauthorized access. It must also allow you to specify what authorized users are allowed to do in the database, such as what data they can read and modify.

Microsoft Dynamics NAV 2009 provides a security system that allows administrators to manage user access to the objects and data in the Microsoft Dynamics NAV database. Because the Microsoft Dynamics NAV database is on SQL Server, the Microsoft Dynamics NAV security system and SQL Server security system work together to help ensure that only authorized users can gain access to the Microsoft Dynamics NAV database.

Note Note

For additional information on installing and running Microsoft Dynamics NAV securely, download the Microsoft Dynamics NAV 2009 Security Hardening Guide from the Microsoft Dynamics NAV 2009 Developer and IT Pro Help page in the Microsoft Download Center.

In This Section

Overview: Setting Up Security

Maintaining Users, Roles, and Permissions

Profiles and Role Centers

Security in the Classic Environment

For additional information about Microsoft Dynamics NAV security and for information about setting up security for Classic client users, see "Installation & System Management: SQL Server Option for the C/SIDE Client" (w1w1isql.pdf) and "Installation & System Management: C/SIDE Database Server for Microsoft Dynamics NAV" (w1w1ism.pdf). These manuals, which are available from the Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center, were created for Microsoft Dynamics NAV 5.0 but are still relevant for most security processes and concepts.

See Also

Concepts

Profiles and Role Centers


Overview: Setting Up Security

Overview: Setting Up Security

You can use the following table as a checklist to help set up a more secure Microsoft Dynamics NAV 2009 environment.

Task | Additional information
Install Microsoft Dynamics NAV software | You must make decisions about where you install Microsoft Dynamics NAV components. See Installing Microsoft Dynamics NAV 2009.
Activate your Microsoft Dynamics NAV license | See How to: Activate the License File.
Create users | See How to: Create Users.
Import RoleTailored roles | You can import an .xml file to add supplemental roles to the Microsoft Dynamics NAV security system: a BASIC role and one role that corresponds to each standard profile in the RoleTailored client. By adding these roles, you create a link between traditional security concepts for Microsoft Dynamics NAV (roles, permissions, and users) and security concepts that are specific to the RoleTailored architecture (profiles and Role Centers). See How to: Import RoleTailored Roles.
Import permissions for the BASIC role | You can import an .xml file that adds permissions for the BASIC role. See How to: Import Permissions for the BASIC Role.
Download permissions for additional roles | You can download permissions for additional roles from PartnerSource. See Downloading Permissions for Additional RoleTailored Roles.
Assign users to roles | You must assign the ALL and BASIC roles to all RoleTailored client users. For more information, see Special Roles. See How to: Assign Users to Roles.
Configure Role Centers | See How to: Configure a Role Center.
Assign users to profiles | See How to: Assign a User to a Profile.

See Also

Concepts

Security in the RoleTailored Environment
Enhancing Microsoft Dynamics NAV Server Security


Enhancing Microsoft Dynamics NAV Server Security

Enhancing Microsoft Dynamics NAV Server Security

Microsoft Dynamics NAV Server is a .NET-based Windows Service application that works exclusively with SQL Server databases. Microsoft Dynamics NAV Server provides an additional layer of security between clients and the database. It leverages the authentication features of the Windows Communications Framework to provide another layer of user authentication and uses impersonation to ensure that business logic is executed in a process that has been instantiated by the user who submitted the request. This means that authorization and logging of user requests are performed on a per-user basis.

Login Account

After you install Microsoft Dynamics NAV Server, the default configuration is for the service to log on using the NT Authority\Network Service account. If Microsoft Dynamics NAV Server and SQL Server are on different computers, then we recommend that you configure Microsoft Dynamics NAV Server to log on using a dedicated Windows domain user account instead. This account should not be an administrator either in the domain or on any local computer. A dedicated domain user account is considered more secure because no other services and therefore no other users have permissions for this account. However, a domain user account typically requires additional work by a domain administrator, especially when all three tiers are installed on separate computers. (See Walkthrough: Installing the Three Tiers on Three Computers for details.)

Disk Quotas

Client users can send files to be stored on Microsoft Dynamics NAV Server, so we recommend that administrators set up disk quotas on all computers running Microsoft Dynamics NAV Server. This can prevent users from uploading too many files, which can make the server unstable. Disk quotas track and control disk space usage for NTFS volumes, which allows administrators to control the amount of data that each user can store on a specific NTFS volume. For more information about disk quotas, see the Disk Quotas Technical Reference on Microsoft TechNet.

Limiting Port Access

The Microsoft Dynamics NAV Setup program opens a port in the firewall on the computer where you install Microsoft Dynamics NAV Server. By default, this is port 7046. Setup does not limit who or what can connect to this port. To improve security, you can consider limiting access to this port to a specific subnet. One way is to use netsh, which is a command-line tool for configuring and monitoring Windows-based computers at a command prompt. The specific version of this command that you would use is netsh firewall set portopening. For example, the following command limits access to port 7046 to the specified addresses and subnets:

CopyCode image Copy Code
netsh firewall set portopening protocol=TCP port=7046 scope=subnet addresses=LocalSubnet

See Also

Tasks

Walkthrough: Installing the Three Tiers on Three Computers

Concepts

Configuring Microsoft Dynamics NAV Server
Overview: Setting Up Security

Other Resources

How to Use the Netsh.exe Tool and Command-Line Switches


Microsoft Dynamics Online Connect

Microsoft Dynamics Online Connect

If your installation includes both the RoleTailored client and the demo database, then you have the option of offering Microsoft Dynamics Online Connect to client users. Microsoft Dynamics Online Connect is a Web service that displays Microsoft Dynamics product and business information from online sources such as CustomerSource and the Microsoft Dynamics online community and provides links into those online sources. The actual list of links is customized for each Role Center.

Microsoft Dynamics Online Connect is displayed by default on some Role Centers, can be configured to be displayed on most other Role Centers, and is unavailable on a few Role Centers. See How to: Include Microsoft Dynamics Online Connect on Role Centers for information on which Role Centers offer Microsoft Dynamics Online Connect, and for information on how to configure Role Centers to either include or exclude Microsoft Dynamics Online Connect.

Security Consideration for Microsoft Dynamics Online Connect

Microsoft Dynamics Online Connect sends the following information about the Microsoft Dynamics NAV software over the Internet to Microsoft:

  • Product name

  • Product version

  • Some license information, but not the license number

  • Country/region version

  • Language

  • Profile, which is based on the Role Center ID

No other information is sent.

Internet Access

If you decide to make Microsoft Dynamics Online Connect available to users, then they will require Internet access to use the service. If you have not previously offered Internet access to users, then you should consider the security implications before implementing Microsoft Dynamics Online Connect.

See Also

Concepts

Security in the RoleTailored Environment


Maintaining Users, Roles, and Permissions

Maintaining Users, Roles, and Permissions

For RoleTailored client users, Microsoft Dynamics NAV 2009 uses Windows authentication to control access to databases. With Windows authentication, Windows logins in Microsoft Dynamics NAV are based on Windows users and groups in the current Active Directory domain.

You use the Classic client to:

  • Create and manage users, roles, and permissions for the RoleTailored client.

  • Configure your environment with a set of default roles.

  • Enhance Microsoft Dynamics NAV security by importing additional roles, including one for each profile in the RoleTailored client.

  • Assign RoleTailored client users to one RoleTailored role.

You then use the RoleTailored client to assign users to the equivalent profile. This aligns users and roles with profiles.

In This Section

About Users

About Roles

About Permissions

See Also

Concepts

Overview: Setting Up Security


About Users

About Users

You create and manage RoleTailored client users with the Classic client. Before you can create a RoleTailored client user, you must create a corresponding user or group in Active Directory.

Note Note

You do not need to create user logins in SQL Server before you create Windows logins.

In This Section

How to: Create Users

How to: Assign Users to Roles

Setting Up Users

Related Sections

About Roles

About Permissions

First User Automatically Has SUPER Role

See Also

Concepts

Security in the RoleTailored Environment


How to: Create Users

How to: Create Users

To create a new user for the RoleTailored client, you create a Windows login in the Classic client. You then manage the user in the RoleTailored client.

You do not need to create user logins in SQL Server before you create a Windows login.

Unless you are using the Enhanced Security Model, you do not need to synchronize new Windows logins. For more information, see Security Model and Synchronization.

Note Note

To add users on a computer running Windows Vista with User Account Control enabled, start the Classic client with administrator privileges. Click Start, right-click Microsoft Dynamics NAV Classic with Microsoft SQL Server, and then click Run as administrator.

Creating a New Windows Login

To create a new Windows login with the Classic client

  1. Click Start, and then click Microsoft Dynamics NAV 2009 Classic with Microsoft SQL Server.

  2. Verify that you are connected to your database.

  3. On the Tools menu, point to Security, and then click Windows Logins.

  4. In the Windows Logins form, click on a blank line, and then enter the ID of an existing Windows user or group in the ID column.

    Use the format DomainName\UserName.

  5. Press TAB to move the cursor to the next line.

    If the specified ID is a valid user or group in the Active Directory domain, then the entry is accepted. Otherwise, an error message is displayed.

    You can also click the lookup button in the ID column to display current Windows users and groups in the domain.

See Also

Tasks

How to: Assign Users to Roles
How to: Create a Profile


How to: Assign Users to Roles

How to: Assign Users to Roles

Microsoft Dynamics NAV 2009 provides a set of standard roles. A role is a set of permissions for a set of objects in the database. You can use roles in the default form, modify roles, or create new roles as your needs require. You then can assign users to these roles.

Viewing Permissions for a Role

To view permissions for a role

  1. Open the Classic client, and then connect to an SQL database.

  2. On the Tools menu, point to Security, and then click Roles.

  3. Select a role, click Role in the lower right corner of the form, and then select Permissions.

Assigning a User to a Role

To assign a user to a role

  1. In the Classic client, on the Tools menu, point to Security, and then click Windows Logins.

  2. Select a user, and then click Roles to open the Roles form.

    Any roles that are already assigned to the selected login are displayed.

  3. Click in the first blank row to select the row, and then click the up arrow in the Role ID field to display a list of roles.

  4. In the Roles form, click in the left column to select a role.

    Note Note

    You cannot select more than one role at a time.

  5. Click OK to return to the list of roles for the selected user.

    The new role is now in the list for the login.

  6. Close the Roles form, and then close the Windows Login form.

See Also

Tasks

How to: Create Users
How to: Assign a User to a Profile

Concepts

About Roles


Setting Up Users

Setting Up Users

Go to the User Setup window in the Classic client to define, on a per-user basis, periods of time during which the user is able to post, and whether Microsoft Dynamics NAV records the amount of time the user is logged on. You can also assign responsibility centers to the user.

To open the User Setup window, click Administration, Application Setup, Users, User Setup.

To set up a user, click to select an existing user, or click on a blank line and enter the ID of an existing Windows user or group in the User ID column.

Note Note

You can set up users only when an application is present in the database.

Fields in the User Setup Window

The fields in the User Setup window define timeframes and other constraints for users:

Field Purpose

Allow Posting From

Specifies the date on which the user is able to begin posting.

Allow Posting To

Specifies the last date on which the user can post.

Register Time

To begin registering the amount of time the user spends working on the current company, click to place a mark in this field.

Sales Resp. Ctr. Filter

Specifies the code for a responsibility center. The user is then assigned to this responsibility center. Click the AssistEdit button to the right of the field to see available responsibility centers.

The Sales responsibility center becomes the default responsibility center when the user creates new sales documents. The user only sees sales orders that are created from their responsibility center.

If you leave this field blank, the default responsibility center in Customer or Company Information (in that order of priority) is used.

Purchase Resp. Ctr. Filter

Specifies the code for a responsibility center. The user is then assigned to this responsibility center. Click the AssistEdit button to the right of the field to see available responsibility centers.

The Purchase responsibility center becomes the default responsibility center when the user creates new purchase documents. The user only sees purchase orders that are created from their responsibility center.

If you leave this field blank, the default responsibility center in Customer or Company Information (in that order of priority) is used.

Service Resp. Ctr. Filter

Specifies the code for a responsibility center. The user is then assigned to this responsibility center. Click the AssistEdit button to the right of the field to see available responsibility centers.

The Service responsibility center becomes the default responsibility center when the user creates new service documents. The user only sees service orders created from their responsibility center.

If you leave this field blank, the default responsibility center in Customer or Company Information (in that order of priority) is used.

For more information on responsibility centers, see the online Help in the RoleTailored client.

See Also

Tasks

How to: Create Users

Concepts

Maintaining Users, Roles, and Permissions


About Roles

About Roles

A role is a set of permissions for a set of objects in the database. You assign roles to users in Microsoft Dynamics NAV 2009 with the Classic client. The names and default permissions for roles correspond to tasks, such as posting orders or fulfilling shipments, in your organization. You can use roles from the following sources:

  • Roles with default permissions are provided with the Classic client.

  • Supplemental roles, which include one role for each standard profile in the RoleTailored client and one BASIC role, are provided in an .xml file on the Microsoft Dynamics NAV installation media. To implement these roles, you import the .xml file into the Classic client. For more information, see How to: Import RoleTailored Roles. You can import permissions for these roles separately.

You can also create new roles with the Classic client.

In This Section

First User Automatically Has SUPER Role

How to: Import RoleTailored Roles

How to: Create a Role

Special Roles

Related Sections

How to: Import Permissions for the BASIC Role

About Users

See Also

Concepts

Security in the RoleTailored Environment


First User Automatically Has SUPER Role

First User Automatically Has SUPER Role

When a user creates a Microsoft Dynamics NAV database by installing the CRONUS International Ltd. demonstration database with Microsoft Dynamics NAV 2009 Setup or by restoring a previously backed-up database, that user is automatically given the SUPER user role in the Microsoft Dynamics NAV security system. The SUPER user role provides permissions to read, use, change, and delete all data and all application objects within the scope of your license. This user must then create additional users and assign appropriate roles to them before using Microsoft Dynamics NAV in a production environment.

For Microsoft Dynamics NAV to work properly, the SUPER user must have the appropriate permissions in SQL Server, such as system administrator or db_creator permissions. When Microsoft Dynamics NAV 2009 Setup creates the CRONUS International Ltd. demonstration database in SQL Server, the current user is added as a database user with db_owner permissions.

See Also

Tasks

How to: Create Users
How to: Assign Users to Roles

Concepts

Profiles and Role Centers


How to: Import RoleTailored Roles

How to: Import RoleTailored Roles

You use the Classic client to manage security for the RoleTailored client. When you install the Classic client, Setup adds the following files that you can import into the Classic client to enhance the security system for the RoleTailored client.

File | Description
UserRoles.xml | Defines 21 supplemental roles, which include one for each standard profile in the RoleTailored client, and a BASIC role. The BASIC role grants users access to required system tables and other fundamental tables and is a prerequisite for all other roles that are defined in UserRoles.xml.
UserRolePermissions.xml | Defines permissions for the BASIC role, specifies which objects users with the BASIC role can access in the database, and specifies the type of access (read, insert, modify, delete, and execute).

By importing these two files into the Classic client, you can start integrating the Microsoft Dynamics NAV 2009 security system with the RoleTailored client. There is no explicit connection between roles and profiles, but by giving users of a particular profile the corresponding role in the Microsoft Dynamics NAV 2009 security system, you help ensure that user database permissions are consistent with their profiles.

Importing Sample Roles

The source .xml file for sample roles is located on the Microsoft Dynamics NAV 2009 installation media.

To import sample roles

  1. In the Classic client, click Administration, click Application Setup, click Company Setup, and then click Data Migration to open the Migration Overview form.

  2. Click in the left column to select the first blank line in the form.

  3. In the TableID column, type 2000000004.

  4. Press TAB to move the cursor from the TableID field.

    User Role is displayed in the Table Name column.

  5. Click the Migration button, and then click Migration fields to open the User Role - Migration Fields form.

  6. In the Include column, select RoleID and Name.

  7. Click OK to return to the Migration Overview form.

  8. Click the Functions button, and then click Import from XML to open the Import Setup Data dialog box.

  9. Locate the UserRoles.xml file.

    The default location is C:\Program Files\Microsoft Dynamics NAV\60\Classic\Company Settings\<locale>\.

  10. Click Open to start the import.

  11. Delete any new roles that you do not need.

  12. Click the Migration button, and then click Apply Migration Data.

    The new roles are added.

Note Note

After importing data into the Microsoft Dynamics NAV security system, you must synchronize the system. On the Tools menu, point to Security, and then click Synchronize All Logins.

Security note Security Note

The following limitations exist if you import the sample roles:

These roles and the permissions that you import are provided as a sample or starting point for an actual configuration. A Microsoft Certified Partner or administrator must further configure these roles and permissions before they can meet customer requirements.

The user will experience permission errors if only these sample roles and permissions are used to set up the Microsoft Dynamics NAV security system.

No legal or other agreements concerning the setup of the Microsoft Dynamics NAV security system can be based on the sample roles and permissions supplied in the .xml files that are described in this topic.

See Also

Tasks

How to: Import Permissions for the BASIC Role

Concepts

Overview: Setting Up Security


How to: Create a Role

How to: Create a Role

You create roles with the Classic client. If the default roles that are provided in the Classic client and the supplemental roles that you can import are not sufficient, then you can create new roles.

To modify a role, navigate to the Permissions (All Objects) window for the role, and then modify the permissions as needed.

Creating a Role

To create a new role with the Classic client

  1. Click Start, and then click Microsoft Dynamics NAV 2009 Classic with Microsoft SQL Server.

  2. On the Tools menu, point to Security, and then click Roles.

  3. On the Edit menu, click New to create an empty line on which to create the new role.

  4. Type an ID for the new role in the Role ID field and a description for the new role in the Name field.

  5. Press TAB to enter the new role in the security system. The roles are then ordered alphabetically by the Role ID field.

  6. Click the role row to select it.

  7. Click the Role button, and then click Permissions to open the Permissions window.

  8. Click All Objects to open the Permissions (All Objects) window for the role.

  9. Type or select the word Yes for all permissions that you are granting this role.

    You can also assign a value of Indirect. For more information, see the "Indirect Permission" section.

  10. Create any security filters that you want to apply to the permissions that you have assigned to the role.

    For information on security filters, see "Installation & System Management: SQL Server Option for the C/SIDE Client" (w1w1isql.pdf). This file is available from the Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center.

  11. Click OK in the Permissions (All Objects) window.

    The role is now defined.

Indirect Permission

The values for table permission are Yes, Indirect, or blank, which indicates no permission. You can use indirect permission to use an object only through another object.

For example, a user can have permission to run codeunit 80, Sales-Post. The Sales-Post codeunit performs many tasks, including modifying table 39, Purchase Line. When the user runs the Sales-Post codeunit, Microsoft Dynamics NAV checks whether the user has permission to modify the Purchase Line table.

  • If not, then the codeunit cannot complete its tasks, and the user receives an error message.

  • If so, the codeunit runs successfully.

However, the user does not need to have full access to the Purchase Line table to run the codeunit. If the user has indirect permission for the Purchase Line table, then the Sales-Post codeunit runs successfully.

When a user has indirect permission, that user can only modify the Purchase Line table by running the Sales-Post codeunit or another object that has permission to modify the Purchase Line table. The user can only modify the Purchase Line table when doing so from supported application areas. The user cannot run the feature inadvertently or maliciously by other methods.

See Also

Tasks

How to: Import RoleTailored Roles

Concepts

Special Roles
About Permissions


Special Roles

Special Roles

The following roles have special definitions that you should note as you implement security for the RoleTailored client.

Role Definition

SUPER

Can read, use, change, and delete all data and all application objects within the scope of your license. Microsoft Dynamics NAV 2009 requires that at least one user is assigned this role in each database.

When a user creates a Microsoft Dynamics NAV database by installing the CRONUS International Ltd. demonstration database with Microsoft Dynamics NAV 2009 Setup or by restoring a previously backed-up database, that user is automatically given the SUPER user role in the Microsoft Dynamics NAV security system. For more information, see First User Automatically Has SUPER Role.

You cannot alter permissions that are granted to the SUPER role.

SUPER (DATA)

Can read, use, change, and delete all data. You typically assign this role to an accounting manager or another role that needs to work with all data but does not need to make changes to Microsoft Dynamics NAV.

SECURITY

Can access tables and functions that are related to security information, which include users and permissions. Users with this role can grant permissions to others but can only grant permissions that they have. Therefore, if you want to create an "area superuser," then you should give the person the SECURITY role and permissions for the areas, such as Purchases & Payables, for which they can grant and revoke permissions for other users.

ALL

Can use fundamental but not high-security tables and functions. You must assign this role to all users except SUPER because this is a prerequisite for all other roles.

BASIC

Is a prerequisite for all other RoleTailored roles and grants access to required system tables and other fundamental tables. The BASIC role is a special role created specifically for the RoleTailored client.

The BASIC role is a supplemental role that you must import manually. For details, see How to: Import RoleTailored Roles. You must also import permissions for the BASIC role. For details, see How to: Import Permissions for the BASIC Role.

Once you have imported the BASIC role and permissions for the BASIC role, assign this role to all users who use the RoleTailored client.

See Also

Concepts

Overview: Setting Up Security
About Permissions


About Permissions

About Permissions

Each role in Microsoft Dynamics NAV 2009 describes a set of access permissions to tables, reports, functions, and other objects. The types of permissions are:

  • Read

  • Insert

  • Modify

  • Delete

  • Execute

When you assign permissions to roles, you should not grant permissions to areas that your license file does not allow you to use. However, granting such permissions does not cause any problems. If you update Microsoft Dynamics NAV or purchase additional application areas, then you must change or add appropriate permissions.

You use the Classic client to view, modify, and create permissions. On the Tools menu, point to Security, and then click Roles. The Roles window displays the IDs and names of all roles in the current database.

Note Note

A table can contain a FlowField that generates sums based on values that are stored in another table. In this case, users must have permission to read both tables or they are not allowed to read the first table.

In This Section

How to: Import Permissions for the BASIC Role

Downloading Permissions for Additional RoleTailored Roles

Related Sections

About Users

About Roles

How to: Import RoleTailored Roles

See Also

Concepts

Security in the RoleTailored Environment


How to: Import Permissions for the BASIC Role

How to: Import Permissions for the BASIC Role

If you imported supplemental roles for the RoleTailored client, as described in How to: Import RoleTailored Roles, then you should also import permissions for the BASIC role.

The BASIC role grants access to required system tables and other fundamental tables and is a prerequisite for all other roles that are defined in the UserRoles.xml file and that you assign to RoleTailored client users. After you import permissions for the BASIC role, you must assign this role to all RoleTailored client users except for users that have the SUPER role.

Importing Permissions for the Sample Roles

To import permissions for the sample roles

  1. In the Classic client, click Administration, click Application Setup, click Company Setup, and then click Data Migration to open the Migration Overview form.

  2. Click in the left column to select the first blank line in the form.

  3. In the TableID column, type 2000000005.

  4. Press TAB to move the cursor from the TableID field.

    Permission is displayed in the Table Name column.

  5. Click the Migration button, and then click Migration Fields to open the User Role - Migration Fields form.

  6. In the Include column, select each field except Object Name.

  7. Click OK to return to the Migration Overview form.

  8. Click the Functions button, and then click Import from XML to open the Import Setup Data dialog box.

  9. Locate the UserRolePermissions.xml file.

    The default location is C:\Program Files\Microsoft Dynamics NAV\60\Classic\Company Settings\<locale>\.

  10. Click Open to start the import.

  11. Click the Migration button, and then click Apply Migration Data.

    Permissions for the BASIC role are added.

See Also

Tasks

How to: Import RoleTailored Roles


Downloading Permissions for Additional RoleTailored Roles

Downloading Permissions for Additional RoleTailored Roles

When you import the UserRolePermissions.xml file, as described in How to: Import Permissions for the BASIC Role, you define a set of permissions for the BASIC role. On PartnerSource, you can find additional .xml files that define permissions for other RoleTailored roles that are defined in the UserRoles.xml file and a document that describes their contents.

Security note Security Note

After you download the .xml files and import permissions into the Microsoft Dynamics NAV 2009 security system, we recommend that you further modify the role permissions to conform to the business processes and security requirements of the specific organization for which you are configuring Microsoft Dynamics NAV.

See Also

Tasks

How to: Import Permissions for the BASIC Role

Concepts

Overview: Setting Up Security


Profiles and Role Centers

Profiles and Role Centers

Configuration and personalization are ways to customize the RoleTailored client to suit the daily tasks for users in specific roles.

  • Configuration: Customizations that an administrator implements, such as presenting a custom home page to all users of a Role Center.

  • Personalization: Customizations that an end user makes, such as changing the user interface of a page to fit individual requirements and preferences.

Configuration

An administrator, SUPER user, or Microsoft Certified Partner performs all configuration tasks. This person configures the Role Center for a specific role and then assigns users to the Role Center. For example, when Susan, an order processor, uses the RoleTailored client, she sees the Order Processor Role Center, which has been customized to help her perform her daily tasks. In configuring Susan's Role Center, the administrator has added or removed UI elements, including items in the navigation pane, page parts, and FactBoxes.

Personalization

End users perform all personalization tasks. Examples of user personalization are:

  • Resizing columns.

  • Changing the contents of drop-down menus.

  • Customizing the navigation pane.

  • Adding or removing FactBoxes.

  • Organizing items in the Quick Access pane.

  • Saving queries or filters.

  • Choosing columns in a list place.

Working with Configuration and Personalization

The following table identifies topics that describe configuration and personalization.

To | See
Learn how to create a profile and assign users to a profile | How to: Create a Profile How to: Assign a User to a Profile
Learn how to work with Role Centers | Working with Role Centers
Learn how to start the RoleTailored client in Configuration mode to configure a Role Center | How to: Open the RoleTailored Client in Configuration Mode
Learn how to configure a Role Center | How to: Configure a Role Center
Walk through the steps involved in configuring the Order Processor Role Center | Walkthrough: Configuring the Order Processor Role Center
Walk through the steps involved in personalizing the Order Processor Role Center | Walkthrough: Personalizing the Order Processor Role Center

See Also

Concepts

Maintaining Users, Roles, and Permissions
Security Concepts
Overview: Setting Up Security


How to: Create a Profile

How to: Create a Profile

You use the Profile card to create unique profiles for end users. Each profile is associated with a Role Center that can then be configured to suit the specific user needs. Profiles are typically associated with job titles in a company.

Creating a Profile

To create a profile

  1. In the RoleTailored client, click Departments, click Administration, and then click RoleTailored Client.

  2. Click Profiles.

  3. In the Action Pane, click New to open the New Profile Card window.

  4. In the Profile ID field, enter an appropriate name that describes the intended role of the user.

  5. In the Owner ID field, click the AssistEdit button to view all available logins, and then select a Windows user login. For more information, see How to: Create Users.

  6. In the Description field, enter a description of the Profile ID, such as Order Processor.

  7. In the Role Center ID field, click the AssistEdit button to view all available Role Centers. Select a Role Center.

  8. To make this Role Center the default profile ID for all users, select the Default Role Center check box.

  9. Click OK to save your changes.

The procedure for modifying an existing profile is largely the same, except you select an existing profile in the Profiles page instead of clicking New.

See Also

Tasks

How to: Configure a Role Center
How to: Assign a User to a Profile
How to: Add Users

Concepts

Working with Role Centers
Profiles and Role Centers
Overview: Setting Up Security


How to: Assign a User to a Profile

How to: Assign a User to a Profile

You use the User Personalization window in the RoleTailored client to assign a user to a profile.

Assigning a User to a Profile

To assign a user to a profile

  1. In the RoleTailored client, click Departments, click Administration, and then click RoleTailored Client.

  2. Click User Personalization to open the User Personalization Card window.

  3. In the User ID field, click the AssistEdit button to view all available user logins.

  4. Select a user login, and then click OK. For more information, see How to: Add Users.

  5. In the Profile ID field, select a profile ID that you have already created. Click the AssistEdit button to view all available profiles.

  6. In the Language ID field, select the appropriate language ID, or leave this field blank.

  7. In the Company field, select a company from the Companies window.

  8. Click OK.

Note Note

The Language ID and Company values are overwritten by user values when the user starts a session.

See Also

Tasks

How to: Create a Profile
How to: Configure a Role Center
How to: Create Users

Concepts

Profiles and Role Centers
Working with Role Centers


Working with Role Centers

Working with Role Centers

A Role Center is a home page in Microsoft Dynamics NAV 2009 for all users of a profile. For example, the Order Processor Role Center has been configured to reflect the tasks and priorities of an order processor. An administrator can then customize this Role Center to meet the needs of a specific role in a specific company. The Order Processor Role Center can then be further personalized on a single computer to meet the needs of a person who is carrying out the job as an order processor. This person can personalize the Role Center by saving queries, adding filters, and adding or removing fields.

Administrator-Configured Elements

You can configure the following elements in Role Centers:

  • Navigation pane

  • FactBoxes

  • Home parts

  • Lists

  • Task pages

  • Action menus

  • Report menus

Preconfigured Role Centers

There are 21 Role Centers available in Microsoft Dynamics NAV. The following Role Centers have been fully configured:

  • 9004 - Bookkeeper Role Center

  • 9005 - Sales Manager Role Center

  • 9006 - Order Processor Role Center

All Role Centers can be used as is or can be reconfigured by an administrator or SUPER user.

See Also

Tasks

How to: Create a Profile
How to: Configure a Role Center
How to: Assign a User to a Profile
How to: Open the RoleTailored Client in Configuration Mode
How to: Import RoleTailored Roles

Concepts

Profiles and Role Centers
Overview: Setting Up Security


How to: Open the RoleTailored Client in Configuration Mode

How to: Open the RoleTailored Client in Configuration Mode

To configure a profile, you must open the RoleTailored client in configuration mode.

To open the RoleTailored client in configuration mode

  1. At the command prompt, navigate to the root folder of the RoleTailored client. For example:

    CopyCode image Copy Code
    cd C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client

  2. Type the following command:

    CopyCode image Copy Code
    Microsoft.Dynamics.Nav.Client.exe -configure -profile:profileid

    Replace profileid with the name of the profile that you want to configure.

    For example, to configure the Accounting Manager profile, use this command to open the RoleTailored client in configuration mode:

    CopyCode image Copy Code
    Microsoft.Dynamics.Nav.Client.exe -configure -profile: "Accounting Manager"

See Also

Tasks

How to: Configure a Role Center
How to: Create a Profile
How to: Assign a User to a Profile

Concepts

Profiles and Role Centers
Working with Role Centers


Starting the RoleTailored Client from a Command Prompt

Starting the RoleTailored Client from a Command Prompt

You can start the RoleTailored client at a command prompt. By adding command-line parameters, you can:

  • Start the RoleTailored client with a profile other than the default profile.

  • Configure a profile.

  • Start the RoleTailored client with a language other than the default language.

  • Start the RoleTailored client with client settings other than the default client settings.

  • Start the RoleTailored client and open the specified page.

  • Start the RoleTailored client and open the specified report.

To run the RoleTailored client at a command prompt, open a command-prompt window and navigate to the RoleTailored client directory. The default location is:

CopyCode image Copy Code
Program Files\Microsoft Dynamics NAV\60\RoleTailored Client

The executable name is:

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe

You can also start the RoleTailored client from the address bar in a browser or from a Run window using the same options. To start the RoleTailored client from a browser, type

CopyCode image Copy Code
DynamicsNAV://<Server/ServerInstance>/<Company>/

For example, to open the CRONUS International Ltd. company you could type

CopyCode image Copy Code
DynamicsNAV://localhost/DynamicsNAV/CRONUS%20International%20Ltd./

Command-Line Parameters

You can use the following parameters when you start the RoleTailored client at a command prompt.

Parameter Meaning

-?

Displays this list of parameters.

-profile: id

Starts the RoleTailored client with the specified profile.

Example

This command starts the RoleTailored client with the Accounting Manager profile:

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe -profile:"Accounting Manager"

-configure

Starts the RoleTailored client in configuration mode. Use configuration mode to configure a profile. To specify which profile to configure, add the -profile parameter.

Example

This command starts the RoleTailored client in configuration mode for editing the Accounting Manager profile:

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe -configure -profile:"Accounting Manager"

See How to: Configure a Role Center for details on configuring profiles.

-language: id

Starts the RoleTailored client with the specified language.

Examples

This command starts the RoleTailored client with locale ID 1033:

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe -language:1033

This command starts the RoleTailored client for the culture named de-DE:

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe -language:de-DE

-settings: file

Starts the RoleTailored client with the specified settings file.

For information on RoleTailored client settings files, see Configuring the RoleTailored Client.

Example

This command starts the RoleTailored client with a version of ClientUserSettings.Config that is not at the default location:

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe -settings:"C:\AuxClientSettings\ClientUserSettings.config"

URL

Opens the RoleTailored client to a particular page or with a particular report.

Examples

This command starts the RoleTailored client and opens to page 21 (the Customer Card):

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe "DynamicsNAV://<Server/ServerInstance>/Company/RunPage?Page=21"

This command starts the RoleTailored client and opens the request page for report 101 (the Customer List):

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe "DynamicsNAV://<Server/ServerInstance>/Company/RunReport?Report=101"

This command runs the same report, assuming the default server, server instance, and company. This version runs from a browser instead of at a command prompt:

CopyCode image Copy Code
DynamicsNAV:////RunReport?Report=101

If you specify a Server and Server Instance, you must also specify a company. But you can specify a company without specifying a Server and Server Instance:

CopyCode image Copy Code
Microsoft.Dynamics.Nav.Client.exe "DynamicsNAV:///Company/RunReport?Report=101"

-failurestacktrace

Sends the stack trace for the RoleTailored client to Windows Clipboard.

See Also

Other Resources

Creating and Running Hyperlinks


How to: Configure a Role Center

How to: Configure a Role Center

When you open the RoleTailored client in configuration mode, you can make changes to a Role Center. These changes then become part of the RoleTailored client for users assigned to the profile associated with the Role Center. For more information, see How to: Open the RoleTailored Client in Configuration Mode.

To customize a Role Center

  1. Open the RoleTailored client in configuration mode.

  2. Click the Customize icon to open the Customize menu.

  3. Click the Customize menu to change the page, the navigation pane, the Actions menu, or the Reports menu.

  4. In the window that opens, make the changes to the appearance of the page, the navigation pane, the Actions menu, or the Reports menu.

  5. Click OK.

To customize the Actions menu

  1. In the Customize Actions Menu window, select the action or actions to remove from the Actions menu.

  2. Click the << Remove button to remove the action.

  3. Use the buttons on the right to rearrange the actions on the menu. Use the Restore Defaults button to restore the original Actions menu.

  4. Click OK.

See Also

Tasks

How to: Create a Profile
How to: Assign a User to a Profile
How to: Open the RoleTailored Client in Configuration Mode

Concepts

Profiles and Role Centers
Working with Role Centers


Resetting Personalization and Configuration Settings

Resetting Personalization and Configuration Settings

All end users have the same personalization options in the RoleTailored client. The administrator or SUPER user has assigned each user a Windows login and allocated one or more roles to each user. These roles constrain user access to functionality in the application. For example, an Order Processing Clerk may only have access to the Order Processing part of the application. This user can personalize everything in this view.

Resetting

Personalization changes made by end users override configuration changes made by the administrator. The administrator can reset a Role Center to its default settings by deleting all entries in the personalization or configuration tables.

  • To clear the configuration table, open the Profile Card window, click Functions, and then select Clear Configured Pages.

  • To clear the personalization table, open the Profile Card window, click Functions, and then select Clear Personalized Pages.

See Also

Tasks

How to: Create a Profile
How to: Configure a Role Center
How to: Assign a User to a Profile
How to: Open the RoleTailored Client in Configuration Mode

Concepts

Profiles and Role Centers
Working with Role Centers


Configuration and Personalization Walkthroughs

Configuration and Personalization Walkthroughs

The section contains one configuration walkthrough and one personalization walkthrough:

  • Configuration tasks are performed by an administrator, SUPER user, or Microsoft Certified Partner. This person configures the Role Center for a specific role and then assigns users to the Role Center.

  • Personalization tasks are performed by the end user and apply only on the user's computer. Users can personalize their Role Center to meet their individual work requirements.

In This Section

Topic | Description
Walkthrough: Configuring the Order Processor Role Center | Demonstrates how to configure the Order Processor Role Center.
Walkthrough: Personalizing the Order Processor Role Center | Demonstrates how to personalize the Order Processor Role Center.

Related Sections

Profiles and Role Centers

Overview: Setting Up Security

See Also

Concepts

Security in the RoleTailored Environment


Walkthrough: Configuring the Order Processor Role Center

Walkthrough: Configuring the Order Processor Role Center

The RoleTailored client provides a customizable user interface that you can modify to support the job functions of different work roles in your organization. The RoleTailored client offers 21 predefined Role Centers. To be able to configure a Role Center, you must be an administrator with the role SUPER. The difference between configuration and personalization is that configuring a Role Center changes the user interface for all users with the same profile, whereas personalizing a Role Center only changes the user interface for a single user.

Configuration tasks are typically performed by an administrator, SUPER user, or Microsoft partner. This person configures the Microsoft Dynamics NAV 2009 user interface (Role Center) to suit a specific role, then assigns users to the Role Center.

Expand image About this Walkthrough

This walkthrough provides examples of how to configure the existing Order Processor Role Center in Microsoft Dynamics NAV. The walkthrough demonstrates how to:

  • Verify that you are the owner of a Role Center.

  • Open the RoleTailored client in configuration mode.

  • Configure the Actions pane.

  • Configure the FactBox pane.

Prerequisites

Before you can perform the steps in this walkthrough, you must:

  • Install Microsoft Dynamics NAV 2009.

  • Install the CRONUS International Ltd. demo database.

Expand image Verifying Ownership of a Role Center

To be able to configure a Role Center, you must own the associated profile.

To verify ownership of a Role Center

  1. Open the Classic client, then go to Administration, expand the Application Setup node, and then click RoleTailored Client, and open Profiles.

    You could also perform this procedure on the RoleTailored client.

  2. Press F5 to display the complete list of profiles.

  3. Double-click ORDER PROCESSOR to open the Sales Order Processor profile card.

  4. For the Owner ID field, click the Assist button and select your login.

  5. Click OK to close the window.

Expand image Opening the RoleTailored Client in Configuration Mode

If you are the owner of the profile, you can open the RoleTailored client in configuration mode for that profile. Changes you make to a Role Center in configuration mode apply to all users associated with the profile. You can undo changes for any UI element using the Restore Defaults button in any dialog box.

To open the RoleTailored client in configuration mode

  1. Open a command line and change to the directory containing the RoleTailored client executable. For example, type the following command: cd c:\Program Files\Microsoft Dynamics NAV\60\RoleTailored client.

  2. Open the RoleTailored client in configuration mode by typing the following command: Microsoft.Dynamics.Nav.Client.exe -configure -profile:"order processor"

    The RoleTailored client opens in configuration mode.

Expand image Configuring the Actions Pane

The Actions pane in the RoleTailored client is a dynamic pane that changes according to which page is currently loaded. The Actions pane for the Order Processor Role Center reflects actions that are appropriate for a person in the order processor role. The next procedure shows how to promote an action to the Process group and add the status report to the Reports group.

To configure the Actions pane

  1. In the RoleTailored client, click the Home tab to go to the home page of the Order Processor Role Center.

  2. In the Navigation pane, click Sales Orders to open the Sales Order page.

  3. In the top right corner, click the Customize button and select Customize Action Pane.

  4. In the Customize window, select Action Pane.

  5. In the Select a group or enter name of new group field, select Process.

  6. Under Available commands, expand Actions, select Notes, and then click the Add>> button.

  7. Click OK to save and close the window.

Expand image Configuring the FactBox Pane

FactBoxes are smaller windows that contain information related to the current main window. They appear at the far right of the page. The procedure below demonstrates how to add FactBoxes to the FactBox pane. The FactBoxes that are available for adding vary according to what has been linked to the page using the Object Designer in the Classic client.

To configure the FactBox pane

  1. In the Home navigation pane, click Sales Orders to open the Sales Order page.

  2. In the top right corner, click the Customize button and select Customize Action Pane.

  3. In the Customize window on the left, select FactBoxes.

  4. From the Available FactBoxes pane, select Links and click the Add>> button.

  5. Click OK to save and close the window.

Expand image Next Steps

In this walkthrough you have configured the Actions menu and the FactBox pane for the Order Processor Role Center. These are just two options you have for changing the user interface of a role center to better fit a specific profile in your company.

All users of the profile see these changes. If there is a need for more specific user settings and changes, each individual of the Role Center can personalize their view by adding or removing functionality that they use often or less frequently. For more information, see Walkthrough: Personalizing the Order Processor Role Center.

Expand image See Also

Tasks

How to: Open the RoleTailored Client in Configuration Mode

Concepts

Profiles and Role Centers
Working with Role Centers
Resetting Personalization and Configuration Settings


Walkthrough: Personalizing the Order Processor Role Center

Walkthrough: Personalizing the Order Processor Role Center

With the RoleTailored client you get a customizable user interface that can be modified to support the job functions of different work roles in your organization. The RoleTailored client provides 21 predefined Role Centers, which users can personalize to suit their own needs.

Personalization tasks are typically performed by the end user and apply only on the user's computer. Users can personalize their Role Center to meet their individual work requirements.

Expand image About this Walkthrough

This walkthrough provides examples of how to personalize the Order Processor Role Center with Microsoft Dynamics NAV. The walkthrough demonstrates how to:

  • Personalize the Navigation pane

  • Personalize the customers list

Prerequisites

Before you can perform the steps in this walkthrough, you must:

  • Install Microsoft Dynamics NAV 2009.

  • Install the CRONUS International Ltd. demo database.

Expand image Personalizing the Navigation Pane

In this procedure, you add a new group to the navigation pane, to provide a shortcut to the Contacts page.

To personalize the Navigation pane

  1. In the RoleTailored client, click the Home tab to go to the home page of the Order Processor Role Center.

  2. In the top right corner, click the Customize button, and select Customize Navigation Pane.

  3. In the Customize Navigation Pane window, click the New button.

  4. In the New Activity Button window, in the Name field give the new group a name. In this example, name the group Contacts.

  5. Select an icon from the list, and click OK.

  6. In the Customize Navigation Pane window, click Add.

  7. In the Add List window, from the Available lists, expand Sales and Marketing, then expand Sales, select Contacts, and click OK.

  8. In the Customize Navigation Pane window, click OK.

    You will see a message informing you that your changes have been saved and will take effect after the application has been restarted.

  9. Click Yes to indicate that you want to restart the application right away.

    Once the application restarts, notice that there is a new tab in the Navigation pane: Contacts.

Expand image Personalizing the Customers List

The standard Order Processor Role Center comes with a predefined set of columns that can easily be adjusted to display needed information. The following show how to add an additional column to the customer list.

To personalize the customers list

  1. In the Navigation pane, click the Home tab and then Sales Orders to open the Sales Order page.

  2. In the top right corner, click the Customize button, and select Customize Action Pane.

  3. In the Customize Sales Orders window, select Choose Columns.

  4. From the Available columns list, select Bill-to Customer No. and click Add.

  5. In the Show columns in this order list, select the just added Bill-to Customer No. and click Move Up until the new item is just under Sell-to Customer Name.

  6. Click OK to save the change and close the window.

    The change is immediate—no restart required this time.

Expand image Next Steps

In this walkthrough you personalized the navigation pane to provide easy access to contacts, and added an extra column to the customer list in the Order Processor Role Center. These are two examples of how you can change the user interface of a role center to better support your job function. The changes affect only the current user on the current computer. If there is a need for more generic user settings and changes, the administrator can configure a Role Center for all users, as described in Walkthrough: Configuring the Order Processor Role Center.

Expand image See Also

Tasks

How to: Open the RoleTailored Client in Configuration Mode
Walkthrough: Configuring the Order Processor Role Center

Concepts

Profiles and Role Centers
Working with Role Centers
Resetting Personalization and Configuration Settings


Security Concepts

Security Concepts

Microsoft Dynamics NAV 2009 provides a security system that manages user access to the objects and data in your database. Because this database is stored in SQL Server, the Microsoft Dynamics NAV security system and the SQL Server security system work together to help ensure that only authorized users can gain access to the information in the database.

When a user creates a Microsoft Dynamics NAV database, that user is automatically given the SUPER user role in the Microsoft Dynamics NAV security system. This allows at least one user who can create additional users and assign appropriate roles to them. For more information, see First User Automatically Has SUPER Role.

The Microsoft Dynamics NAV security system allows you to control which objects, such as tables, that each individual user can access within each database. It also allows you to specify which particular records or information that is stored in these tables that each user is allowed to access. For more information, see "Limiting Access to Specific Database Entries" in Customizing Security. You can manage user access at both the table or record level.

In This Section

Security Model and Synchronization

Customizing Security

Related Sections

Maintaining Users, Roles, and Permissions

Profiles and Role Centers

Overview: Setting Up Security

See Also

Concepts

Security in the RoleTailored Environment


Security Model and Synchronization

Security Model and Synchronization

When you create a database, you must specify the security model. There are two options:

  • Standard Security

  • Enhanced Security (default)

The Security Model option is on the Advanced tab in the New Database window.

Security Model Differences

Enhanced Security provides an individual layer of protection for each Microsoft Dynamics NAV user. Standard Security does not have this extra layer but can be sufficient for most companies. Using Enhanced Security can impact Microsoft Dynamics NAV performance.

The following table shows the significant differences:

Feature | Standard Security | Enhanced Security
Synchronization performance | Fast | Slower, especially if you have several companies and many users in the same database
Windows groups available | Local domain plus forest of domains | Local domain only; restricted set of groups available
Logins required in Microsoft Dynamics NAV | Windows groups or individual Windows users | Windows groups plus the members of each group; individual Windows users
Granularity of synchronization | Entire security system | Entire security system and individual logins
Automatic synchronization when you insert, modify or delete a Windows login | Yes | No

Synchronization

Microsoft Dynamics NAV 2009 provides a synchronization mechanism to ensure that information in the SQL Server security system corresponds with the information that is contained in the Microsoft Dynamics NAV security system. When Microsoft Dynamics NAV security is not synchronized with SQL Server security, users may not have the exact database access that the administrator has specified.

When you are running with the Enhanced Security model, there is no automatic synchronization. You must manually synchronize whenever you insert, modify or delete a Windows login. In the Classic client, on the Tools menu, point to Security, and then click Synchronize All Logins.

When to Synchronize

With the Standard Security model, explicit synchronization is only necessary when you are restoring a database from a backup. With the Enhanced Security model, you must manually synchronize the Microsoft Dynamics NAV security system after you:

  • Change the security model.

  • Modify Microsoft Dynamics NAV users, permissions, or roles.

  • Restore a backup.

  • Convert a database.

  • Update the executable files.

  • Update the application.

See Also

Tasks

How to: Create Users

Concepts

Security Concepts


Customizing Security

Customizing Security

Microsoft Dynamics NAV 2009 provides options for limiting and monitoring user access to the database. You can find detailed discussions of these options in "Installation and System Management: SQL Server Option for the C/SIDE Client" (w1w1isql.pdf). This manual, which is available from the Microsoft Dynamics NAV 5.0 Developer and Installation Guides page in the Microsoft Download Center, was created for Microsoft Dynamics NAV 5.0 but is still relevant for background information on many security processes and concepts.

Security Customization Options

Use the following options to limit user access beyond the permission level:

Limiting Access to Specific Database Entries

You can specify that each individual user or group can only access specific entries in the database. For example, you can limit access to the entries that relate to a specific department or project. This level of access control is known as record level security. For information on implementing record level security, see "Applying Security Filters" in w1w1isql.pdf.

Time-Limited Passwords

Passwords in Microsoft Dynamics NAV do not have time limits, but you can put time limits on user IDs.

If you have the required permissions, then you can delete a user ID from the system or cancel all permissions. If deleting a user ID is too drastic a step to take, then you can specify a limited time period during which a particular user ID is allowed to post in the system. You set up this limitation in the User Setup window. For more information, see Setting Up Users.

Registering User Time

You can specify that you want Microsoft Dynamics NAV to register the amount of time that each user works with a company in the database. To see the time use that has been registered, in the Classic client, click General Ledger. Click Setup, click Users, and then click User Time Registers.

To register user time, use the User Setup window. In the Classic client, click Administration, and then click Application Setup. Click Users, and then click User Setup.

To see the time use that has been registered, in the Classic client, click General Ledger. Click Setup, click Users, and then click User Time Registers.

For more information, see "User Time Register" in w1w1isql.pdf.

Default and Fixed Printer Selections

You can specify which printer that each individual user can use. In the Classic client, click General Ledger, click Setup, and then click Printer Selections. For more information, see "Selecting a Printer" in w1w1isql.pdf.

See Also

Concepts

Setting Up Users
Maintaining Users, Roles, and Permissions


Development Considerations

Development Considerations

Before you begin developing code for Microsoft Dynamics NAV 2009, you should consider the following:

  • How to get started learning C/AL.

  • How to build on your C/AL knowledge.

  • How to build an application by using your knowledge of C/AL.

  • What you need to do to develop applications on both the Classic client and the RoleTailored client.

  • What the differences are between developing in Microsoft Dynamics NAV 2009 and previous versions of Microsoft Dynamics NAV.

  • How to upload and download files between the server and the client.

Developing in Microsoft Dynamics NAV 2009

To See

Learn what you can do with C/AL and where to place C/AL code.

Using C/AL

Learn what the C/AL data types are.

C/AL Data Types

Learn how to write C/AL statements and expressions.

  • Statements and Expressions

  • Elements of C/AL Expressions

  • C/AL Control Statements

Learn about debugging C/AL.

Debugging C/AL Code

Learn how to test customized objects for which code has been executed.

Code Coverage Tool

Learn about using custom controls with C/AL.

Extending Microsoft Dynamics NAV Using COM

Learn about the development environment (C/SIDE) and designing applications.

  • C/SIDE Fundamentals

  • Designing C/SIDE Applications

Learn about developing for multiuser environments.

Multiuser Environments

Learn about using multilanguage functionality.

Working with Multilanguage Functionality

Learn the differences in how numerical values are sorted.

Sorting Numerical Values

Learn how to use display language-specific strings without modifying code.

CaptionClass Functionality

Learn about developing applications for both the Classic client and the RoleTailored client.

Developing Applications for the Classic Client and RoleTailored Client

Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client

Learn about differences between developing in Microsoft Dynamics NAV 2009 and previous versions of Microsoft Dynamics NAV.

Changes in C/AL Behavior and Support from Previous Versions of Microsoft Dynamics NAV

Learn about transferring files between the client and the server.

File Handling


Introduction to C/AL

Introduction to C/AL

The topics in this section introduce the C/AL language. They describe the syntax of the language, how to use the language to create functions, how to compile and debug C/AL code, and how to extend C/AL by using COM technologies.

See Also

Concepts

Using C/AL
Compiling Objects
Debugging C/AL Code
Using Zoom
Using About This Page and About This Report
Code Coverage Tool
Extending Microsoft Dynamics NAV Using COM


Using C/AL

Using C/AL

This section describes where to write C/AL code and how to reuse code.

For more information about using system-defined variables, see System-Defined Variables.

For more information about the most commonly used C/AL functions, see Essential C/AL Functions.

Where to Write C/AL Code

Almost every object in C/SIDE contains triggers where you can place your C/AL code. Triggers exist for the following objects:

  • Tables

  • Table fields

  • Forms, including request forms

  • Form controls

  • Reports

  • Data items

  • Sections

  • Pages

  • XMLports

  • Dataports

You can initiate the execution of your C/AL code from the following:

  • Command buttons

  • Menu items

  • Any object that has an instantiation of the object that contains C/AL code. An example of an instantiation is a variable declaration.

    Note Note

    If the C/AL code is in a local function, then you cannot run it from another object.

Guidelines for Placing C/AL Code

We recommend the following guidelines for placing C/AL code:

  • In general, place the code as close as possible to the object on which it will operate. This implies that code which modifies records in the database should normally be placed in the triggers of the table fields that are involved.

  • In reports, always maintain a clear distinction between logical and visual processing and position your C/AL code accordingly. This implies that it is acceptable to have C/AL code in a section trigger if that code controls either the visual appearance of the controls or whether the section should be printed. Never place code that manipulates data that is in the database in section triggers.

  • The principle of placing code near the object on which it operates can be overruled in some situations. One reason to overrule this principle is security. Normal users do not have direct access to tables that contain sensitive data, such as the General Ledger Entry table, nor do they have permission to modify objects. If you place the code that operates on the general ledger in a codeunit, give the codeunit access to the table, and give the user permission to execute the codeunit, you will not compromise the security of the table and the user will be able to access the table.

  • There are reasons other than security for putting a posting function in a codeunit. A function that is placed in a codeunit can be called from many places in the application, including, perhaps, some that you did not anticipate when you first designed the application.

  • If you need user input for a function, such as a filter or sorting key, then we recommend that you use the RunObject Property of the menu item and then set a record as a parameter by reference on the codeunit that the RunObject property calls. For more information, see Programming Guidelines for Functions in Forms.

Reusing Code

The most important reason for placing C/AL code consistently, and as close to the objects that it manipulates, is that it lets you reuse code. Reusing code makes developing applications both faster and easier. More importantly, if you place your C/AL code as suggested, your applications will be less prone to errors. By centralizing the code, you will not inadvertently create inconsistencies by performing essentially the same calculation in many places, for example, in a number of control triggers that have the same table field as their source expression. If you have to change the code, you could easily either forget about some of these controls or make a mistake when editing one of them.

See Also

Concepts

System-Defined Variables
Essential C/AL Functions


Standard and User-Defined Functions

Standard and User-Defined Functions

To create an application in Microsoft Dynamics NAV, you must make database objects work together. You can use C/AL code to bind all the database objects together to form a unified whole.

When you design professional applications you often need specialized functions. C/AL lets you create functions that extend the functionality of C/SIDE. You can create special functions for use anywhere in the database.

C/AL enables you to:

  • Design your own functions

  • Use standard, built-in functions

  • Connect database objects

  • Read, write, and modify data

Designing Your Own Functions

Although C/SIDE has many built-in functions, you may need or want to create your own functions. For example, you will need to develop your own functions when the application that you develop repeatedly uses the same nontrivial processing.

We recommend the following guidelines for when to create new functions and when to create parameters and local variables for a function:

  • Do not move a piece of code to a new function unless either the code is nontrivial and the new function is afterwards called from more than one place, or the move is required to keep the code clear and manageable.

  • Create only parameters that are necessary for the function to operate on different data, depending on where it is called from. If a function also changes a global variable, however, then we recommend that you transfer the global variable to the function to indicate that the function will change this variable.

  • Use additional local variables in the same way that you would use them in other development languages and environments.

  • When you create a user-defined function, we recommend that you set the Local property to Yes unless you want to access the function from outside the object. This makes the code easier to understand because it is clear that the function is not referenced from other objects.

See Also

Concepts

Essential C/AL Functions
C/AL Functions


Statements and Expressions

Statements and Expressions

A C/AL statement is a code instruction that when executed, causes operations to occur, which can alter one or more variables or initiate read and write transactions to the database.

A C/AL statement is built from expressions.

A C/AL expression is a group of characters (data values, variables, arrays, operators, and functions) that can be evaluated, with the result having an associated data type. An expression is a fundamental C/AL concept. All expressions in C/AL are built from the following:

  • Constants

  • Variables

  • Operators

  • Functions

  • Keywords

For more information about constants, variables, operators, functions, and keywords, see Elements of C/AL Expressions.

Example 1

For this example, consider the following C/AL code.

CopyCode image Copy Code
Amount := 34 + Total;

This line of code is also called a statement. The following table illustrates how the statement can be broken into smaller elements.

Element | Description
34 + Total | An expression. This expression consists of an arithmetic operator (+) and two arguments (34 and Total), which also could be called sub-expressions. Every valid C/AL expression can be evaluated to a specific value.
:= | The assignment operator. When the expression on the right side has been evaluated, this operator is used to assign or store the value in the variable on the left side.
Amount | A variable. Used to reference a memory location where data is stored.

Example 2

An expression can be used as an argument for a C/AL function. Consider the following C/AL statement.

CopyCode image Copy Code
Date := DMY2DATE(31, 12, 2001);

This function takes three simple expressions as arguments: 31, 12, and 2001.

Typical Expressions

Depending on the elements in the expression, the evaluation results in a value with a C/AL data type. The following table shows some typical expressions.

Expression | Evaluates to | Description
'Welcome to Hawaii' | The string 'Welcome to Hawaii' | Evaluates to itself
'Welcome ' + 'to Hawaii' | The string 'Welcome to Hawaii' | Evaluates to a concatenation of the two strings
43.234 | The number 43.234 | Evaluates to itself, a decimal number
ABS(-7234) | The number 7234 | A function that evaluates to a number
len1 < 618 | TRUE or FALSE, depending on the value of len1 | A comparison between a variable and a numerical constant, which evaluates to a Boolean value

These examples show that when C/AL expressions are evaluated, the results have a specific data type. For more information about data types, see C/AL Data Types.


C/AL Data Types

C/AL uses variables to store data of various types. By declaring variables of the correct type, you do the following:

  • Create faster code

  • Save space

  • Avoid run-time errors because of overflow

  • Avoid run-time errors that are caused by impossible type conversions

For example, if you know that a variable will always contain a number between 0 and 700, then you should use an integer variable instead of a decimal variable. Any calculations that are performed will be faster because four bytes per integer operation are used instead of twelve bytes per decimal operation. However, you must use a data type that can hold every possible value that is needed in your calculations. For example, if you try to store the value 1233.345 in an integer variable, then the result will be an error.

C/AL Data Types

The following table shows the C/AL data types. All C/AL data types are either fundamental or complex. Some data types can also be divided into other categories.

Data type | Fundamental or complex | Other categories
BigInteger Data Type | Fundamental | Numeric
Char Data Type | Fundamental | Numeric
Decimal Data Type | Fundamental | Numeric
Duration Data Type | Fundamental | Numeric
Integer Data Type | Fundamental | Numeric
Option Data Type | Fundamental | Numeric
Code Data Type | Fundamental | String
Text Data Type | Fundamental | String
Binary Data Type | Fundamental |
Boolean Data Type | Fundamental |
Date Data Type | Fundamental |
DateTime Data Type | Fundamental |
Time Data Type | Fundamental |
Automation Data Type | Complex |
BigText Data Type | Complex |
BLOB Data Type | Complex |
Codeunit Data Type | Complex |
DateFormula Data Type | Complex |
Dialog Data Type | Complex |
File Data Type | Complex |
FieldRef Data Type | Complex |
Form Data Type | Complex |
GUID Data Type | Complex |
InStream and OutStream Data Types | Complex |
KeyRef Data Type | Complex |
OCX Data Type | Complex |
Page Data Type | Complex |
Record Data Type | Complex |
RecordID Data Type | Complex |
RecordRef Data Type | Complex |
Report Data Type | Complex |
System | Complex |
TableFilter Data Type | Complex |
Variant Data Type | Complex |

Fundamental Data Types

Fundamental data types are designed to store Boolean values, numbers, text, time, and dates.

BigInteger Data Type

The BigInteger data type stores very large whole numbers within the range

-9,223,372,036,854,775,807 to 9,223,372,036,854,775,807.

Char Data Type

The Char data type stores a single character as a value in the range 0 to 255. This data type can be freely converted between a number and a character. This means that you can use the same mathematical operators as you can with a variable of a numerical data type.

For example, you can assign a constant string of length 1 to a char variable.

CopyCode image Copy Code
C := "A";

You can also assign a single char in a Text, Code, or Binary data type variable to a Char variable.

CopyCode image Copy Code
C := S[2];

You can also assign a numeric value to a char variable. This will cause the char variable to contain the character from the ASCII character set that corresponds to the numeric ASCII code.

CopyCode image Copy Code
C := 65;

Decimal Data Type

In the Classic client, the Decimal data type denotes decimal numbers ranging from -10+E63 to +10+E63. The exponent ranges from -63 to +63. Decimal numbers are held in memory with 18 significant digits. Although you can store decimal numbers ranging from -10+E63 to +10+E63, you cannot specify a number outside the range +/- 999,999,999,999,999.99 in the UI or in code.

In SQL Server, you can store a decimal number with up to 18 digits and 20 decimal place digits. However, if a number is more than 15 digits, then you cannot enter it in SQL Server or view it in the UI.

In the RoleTailored client, you can store a decimal number with up to 29 digits and precision of 18 digits.

In general, we recommend that you construct decimals that operate on numbers within the range of +/- 999,999,999,999,999.99. Although you can construct larger numbers in some cases, overflow, truncation, or loss of precision can occur.

Duration Data Type

The Duration data type represents the difference between two DateTimes, in milliseconds. For example, you can calculate the difference between two DateTimes by running the following code. This example requires that you define the following variables.

Variable | Data type
DateTime1 | DateTime
Datetime2 | DateTime
Duration | Duration

This example is run on a computer with the Current Format in the Regional and Language Options set to English (United States).

CopyCode image Copy Code
DateTime1 := CREATEDATETIME(010109D, 080000T); // January 1, 2009 at 08:00:00 AM
DateTime2 := CREATEDATETIME(050509D, 133001T); // May 5, 2009 at 1:30:01 PM
Duration := DateTime2 - DateTime1;
MESSAGE(FORMAT(Duration));

The message window displays the following:

124 days 4 hours 30 minutes 1 second

Integer Data Type

The Integer data type stores integers between -2,147,483,647 and 2,147,483,647.

Option Data Type

The Option data type denotes an option value. The Option type is a zero-based enumerator type. Therefore, you can convert option values to integers. For example, assume that Number is a numeric variable and that Type denotes a field of type Option in the Purchase Header table. The following statement converts the option value to a number.

CopyCode image Copy Code
Number := "Purchase Header".Type;

In another example, the following code shows how to use the possible values of an option field as constants.

CopyCode image Copy Code
"Purchase Header".Type := "Purchase Header".Type::Invoice;

Code Data Type

The Code data type denotes a special type of text string. When a given text is assigned to a variable of data type Code, the text is changed to uppercase and any leading and trailing spaces are removed. You can index any character position in a string, for example, A[65]. The resulting values will be of the Char data type. The length of a variable of data type Code always corresponds to the number of characters in the text without leading and trailing spaces. The maximum length of a variable of data type Code is 1024 characters. The maximum length of a table field of data type Code is 250 characters.

The following table shows some typical examples of Code string assignments. In the following examples, it is assumed that the variable c is of data type Code, and has a maximum length of 4.

Assignment | Variable c contains | Length
c := 'AbC'; | 'ABC' | 3
c := '1'; | '1' | 1
c := ''; | '' (empty string) | 0 (zero)
c := '2'; | '2' | 1
c := '1 2'; | '1 2' | 3

Text Data Type

The Text data type denotes a text string. The length of the string ranges from 1 to 1024 characters. You can index any character position in a string, for example A[65] refers to the 65th character in the variable called A. The resulting values will be of data type Char. The length of a variable of data type Text corresponds to the number of characters in the text. For example, an empty text string has length 0.

The following table shows some typical examples of text strings. In these examples, it is assumed that the variable t is of data type Text and has a maximum length of 6.

Assignment | Result
t := 'AbC' | The variable t now contains "AbC"
t := '123456abx'; | Gives a run-time error because the length (9) exceeds the maximum length (6)

When you use the Text and Code data types, it is important to distinguish between the maximum length of the string and the actual length of the string. The maximum length is the upper limit for the number of characters in the string. The actual length describes the number of characters used in the string. The STRLEN Function (Code, Text) and the MAXSTRLEN Function (Code, Text) illustrate this.

CopyCode image Copy Code
t := 'AbC';
STRLEN(t); // Returns 3.
MAXSTRLEN(t); // Returns 6.
t := '12345';
STRLEN(t); // Returns 5.
MAXSTRLEN(t); // Returns 6.

Boolean Data Type

The possible values of Boolean data types are TRUE or FALSE.

Date Data Type

The Date data type denotes dates ranging from January 3, 0001 to December 31, 9999. An undefined date is expressed as 0D. The undefined date is considered to be before all other dates. When you work with dates, you must consider the case in which a date is undefined. For example, if the due date for an invoice is not specified and you create a report that displays all due invoices on a certain date, then you must handle the undefined date. Otherwise, the invoice with the unspecified date will appear to be long overdue, which may not be true.

All dates have a corresponding closing date. The closing date for a given date is regarded as a period following the given date but before the next normal date. A closing date is therefore sorted immediately after the corresponding normal date but before the next normal date.

DateTime Data Type

The DateTime data type denotes a date and the time of day. The DateTime is stored in the database as Coordinated Universal Time (UTC). UTC is the international time standard (formerly Greenwich Mean Time, or GMT). Zero hours UTC is midnight at 0 degrees longitude. The DateTime is always displayed as local time in Microsoft Dynamics NAV. Local time is determined by the time zone regional settings used by your computer. You must always enter DateTimes as local time. When you enter a DateTime as local time, it is converted to UTC using the current settings for the time zone and daylight saving time.

There is only one constant available when you use this data type: undefined datetime, which is expressed as 0DT.

The range of a DateTime depends on whether you are using the Microsoft Dynamics NAV Classic Database Server, or SQL Server.

  • Classic Database Server

    The earliest permitted DateTime is January 3, 0001, 00:00:00.000.

    The latest permitted DateTime is December 31, 9999, 23:59:59.999.

  • SQL Server

    The earliest permitted DateTime is January 1, 1753, 00:00:00.000.

    The latest permitted DateTime is December 31, 9999, 23:59:59.999.

    Any DateTimes that are not within this range and that you try to enter or construct by, for example, adding a DateTime to a Duration, are regarded as undefined DateTimes and give an error message.

    Undefined dates in Microsoft Dynamics NAV are stored as January 1, 1753, 00:00:00.000, which is the earliest permitted DateTime in SQL Server.

Time Data Type

The Time data type denotes a time ranging from 00:00:00 to 23:59:59.999. An undefined time is expressed as 0T.

Descriptive Data Types

The following table shows the relationship between the descriptive data types and the simple C/AL data types.

Descriptive data type Included system data types

Numeric

  • Char

  • Integer

  • BigInteger

  • Duration

  • Option

  • Decimal

String

  • Text

  • Code

Complex Data Types

Complex data types are used when you need to work with, for example, records in tables, pictures (bitmaps), or disk files. C/AL is object-based so each complex data type can include both member variables and member functions.

C/SIDE is not object-oriented but object-based. This is an important distinction. In an object-oriented language or environment, you can create new types of objects that are based on the ones already in the system. In C/SIDE, you have eight types of application objects. You can create and use Tables, Pages, Forms, Reports, Dataports, XMLports, Codeunits, and MenuSuites, but you cannot create any other objects.

Automation Data Type

For more information about the Automation data type, see Extending Microsoft Dynamics NAV Using COM.

BigText Data Type

The BigText data type contains large text documents. Data of the BigText data type cannot be displayed in the debugger or in a message window. However, you can use the BigText functions to extract part of a big text and place it in a normal text string that can be displayed. The BigText functions are:

  • ADDTEXT Function (BigText)

  • GETSUBTEXT Function (BigText)

  • LENGTH Function (BigText)

  • READ Function (BigText)

  • TEXTPOS Function (BigText)

  • WRITE Function (BigText)

The maximum length of a BigText variable is 2147483647 characters. This is the equivalent of 2 gigabytes (GB).

BLOB Data Type

A BLOB is a Binary Large Object. Variables of this data type differ from normal numeric and string data type variables in that they have a variable length. BLOBs are used to store memos (text), bitmaps (pictures), or user-defined types. The maximum size of a BLOB is often determined by your system’s disk storage capacity. The upper limit is 2GB.

Codeunit Data Type

The Codeunit data type stores codeunits. A codeunit can contain a number of user-defined functions.

DateFormula Data Type

The DateFormula data type contains a date formula that has the same capabilities as an ordinary input string for the CALCDATE function. The DateFormula data type is used to provide multilanguage capabilities to the CALCDATE function.

Dialog Data Type

The Dialog data type stores dialog windows. A number of functions are available for manipulating dialogs.

File Data Type

The File data type provides access to operating system files.

FieldRef Data Type

The FieldRef data type identifies a field in a table and gives you access to this field. The FieldRef object can refer to any field in any table in the database.

Form Data Type

The Form data type stores forms. This data type can contain a number of simpler elements called controls. Controls are used to display information to the user or to receive user input.

GUID Data Type

The GUID data type gives a unique identifying number to any database object.

The GUID data type is a 16-byte binary data type. This data type is used for the global identification of objects, programs, records, and so on. The most important property of a GUID is that each value is globally unique. The value is generated by an algorithm, developed by Microsoft, which assures this uniqueness.

The GUID is a 16-byte binary data type and can be logically grouped into the following subgroups: 4byte-2byte-2byte-2byte-6byte. The standard text representation is {12345678-1234-1234-1234-1234567890AB}.

InStream and OutStream Data Types

The InStream and OutStream data types enable you to read from or write to files and BLOBs. In addition, you can use InStream and OutStream to read from and write to objects of the Automation and OCX data types.

KeyRef Data Type

The KeyRef data type identifies a key in a table and the fields in this key. This gives you access to the key and the fields it contains. The KeyRef object can refer to any key in any table in the database.

OCX Data Type

For more information about the OCX data type, see Extending Microsoft Dynamics NAV Using COM.

Page Data Type

The Page data type stores pages that can contain a number of simpler elements called controls.

Record Data Type

The Record data type consists of a number of simpler elements called fields. A record corresponds to a row in a table. Each field in the record is used to store values of a certain data type. The fields are accessed using the variable name of the record (often the same as the name of the corresponding table), a dot (a period), and the field name. A record is typically used to hold information about a fixed number of properties.

RecordID Data Type

The RecordID data type contains the table number and the primary key of a table. You can store a RecordID in the database but you cannot set filters on a RecordID.

RecordRef Data Type

The RecordRef data type references a record in a table. Typically you use a RecordRef in functions that must apply to all tables, not to a specific table.

If one RecordRef variable is assigned to another RecordRef variable, then they both refer to the same table instance.

Report Data Type

The Report data type stores reports. It can contain a number of simpler elements called controls. Controls are used to display information to the user.

TableFilter Data Type

The TableFilter data type applies a filter to another table. This data type can only be used when you are setting security filters from the Permission table.

Variant Data Type

The Variant data type can contain the following C/AL data types:

  • Record

  • File

  • Action

  • Codeunit

  • Automation

  • Boolean

  • Option

  • Integer

  • Decimal

  • Char

  • Text

  • Code

  • Date

  • Time

  • Binary

  • DateFormula

  • TransactionType

  • InStream

  • OutStream.

Arrays of Variables

You can create 10-dimensional variables using the simple and complex data types. There are no limitations on how many elements a dimension can contain but an array variable can never have more than 1,000,000 elements. The physical size of an array is limited to 2 GB (or available memory). Arrays are always indexed with a number for each dimension that ranges from 1 to (and including) the size of the dimension. If you accidently index outside the range of the dimensions of an array, a run-time error occurs.

For example, assume that SampleArrayVariable is a one-dimensional array variable of data type Integer, with the dimension 10. To index the first element, use SampleArrayVariable[1]. To index the last element, use SampleArrayVariable[10].

As another example, assume that SampleArrayVariable2 is an array variable of data type Date with the dimensions 2x3x4. SampleArrayVariable2 has 24 elements. To index the first element, use SampleArrayVariable2[1,1,1]. To index the last element, use SampleArrayVariable2[2,3,4].

To declare a variable as an array, open the Properties window for the variable and then set the Dimensions property. For more information, see Dimensions Property.


Type Conversion

Type Conversion

This topic describes all possible type conversions in C/AL expressions. It is divided into the following sections:

  • Type Conversion in Expressions

  • Type Conversion Mechanisms

To | See
Learn about using expressions to convert types. | Type Conversion in Expressions
Learn about the conversion categories. | Type Conversion Mechanisms
Learn about relation operators. | Relational Operators
Learn about Boolean operators. | Boolean (Logical) Operators
Learn about arithmetic operators. | Arithmetic Operators
Gain an overview of type conversion rules for the arithmetic operators. | Type Conversion Rules for Arithmetic Operators

See Also

Concepts

Development Considerations


Type Conversion in Expressions

Type Conversion in Expressions

This topic examines type conversions in C/AL expressions.

C/AL Expression Statements and Type Conversion

Consider the following statements:

CopyCode image Copy Code
CharVar := 15; // A char variable
integerVar := 56000; // An integer variable
Sum := CharVar + integerVar;

The last statement involves one or two type conversions. The rightmost statement involves the evaluation of the expression CharVar + integerVar (char + integer). In order to evaluate this expression, the first operand (CharVar) will have to be converted from char to integer. The addition operator will then return an integer result.

If the type of the leftmost variable has been declared as, for example, decimal, the result must be converted from integer to decimal before its value can be assigned to Sum. For more information, see the section called Assignment and Type Conversion in C/AL Variables.

The following examples describe the type conversions which can take place when expressions are evaluated. The following guidelines are used:

  • When asked to evaluate an expression of mixed data types, the system will (if possible) always convert at least one of the operands to a more general data type.

  • The data types in the two main groups, numbers and strings, can be ranked from "most general" to "least general."

  • The most general data types include all the possible values from the less general data types: a decimal is more general than an integer, which is more general than a char.

  • Type conversion can take place in some cases even though two operands have the same type.

These rules can be illustrated by the following examples.

Example 1

The following example shows the evaluation of a numeric expression.

CopyCode image Copy Code
integer + decimal

This expression contains two sub-expressions of different data types. Before it can add these two sub-expressions, the system must convert the leftmost sub-expression to decimal.

CopyCode image Copy Code
decimal + decimal

When the leftmost sub-expression has been converted, the expression can be evaluated, and the resulting data type will be decimal.

CopyCode image Copy Code
decimal + decimal = decimal

Example 2

The following example shows the evaluation of a string expression.

CopyCode image Copy Code
text + code

This expression contains two sub-expressions that must be concatenated. To do this, the system must convert the sub-expression of the least general data type (code) to the most general data type (text).

CopyCode image Copy Code
text + text

When the rightmost argument has been converted, the expression can be evaluated, and the resulting data type will be text.

CopyCode image Copy Code
text + text = text

See Also

Concepts

Type Conversion
Type Conversion Mechanisms


Type Conversion Mechanisms

Type Conversion Mechanisms

The starting point is to divide the operators into some main categories.

Type Conversion Mechanism Categories

The starting point is to divide the operators into some main categories:

  • Relational operators

    For more information, see Relational Operators.

  • Logical operators

    For more information, see Boolean (Logical) Operators.

  • Arithmetic operators

  • For more information, see Arithmetic Operators.

This section discusses the properties of operators in C/AL. For each category of operators, there are descriptions of the valid data types for the arguments and the data types that result when expressions are evaluated.

Relational operators are the most common conversion mechanisms for the C/AL data types.

See Also

Concepts

Relational Operators
Boolean (Logical) Operators
Arithmetic Operators


Relational Operators

Relational Operators

The relational operators are used to compare expressions.

Evaluation Rules for Relational Operators

The following table defines the evaluation rules for relational operators. The rules assume that the data types of the expressions can be compared. Refer to the next section, "Valid Uses of Relational Operators", for a complete overview of comparable data types.

Operator | Operator name | Expression | Resulting date type
> | Greater than | Expr > Expr | Boolean
< | Less than | Expr < Expr | Boolean
>= | Greater than or equal | Expr >= Expr | Boolean
<= | Less than or equal | Expr <= Expr | Boolean
<> | Not equal to | Expr <> Expr | Boolean
= | Equal to | Expr = Expr | Boolean
IN | In range | Expr IN [Valueset] | Boolean
Note Note

When using relational operators, uppercase and lowercase letters in strings are significant. Furthermore, the comparison is based on the built-in character comparison table of the system, that is, not by comparing "true" ASCII characters.

Valid Uses of Relational Operators

The following table describes the valid uses of the relational operators and the data types that result when expressions are evaluated. The invalid combinations of types for relational operators are indicated by a dash. All relational operators are binary infix operators; that is, they take a left and a right argument and are placed between the arguments.

The rows in the table show the type of the left argument and the columns show the type of the right argument. The cells show the resulting data type.

A valid use of the relational operators is, for example, text compared with text or code, while Boolean cannot be compared with anything other than Boolean, and so on.

Relational operator | Boolean | Char | Option | Integer | Decimal | Date | Time | Text | Code
Boolean | Boolean |  |  |  |  |  |  |  |
char |  | Boolean | Boolean | Boolean | Boolean |  |  |  |
option |  | Boolean | Boolean | Boolean | Boolean |  |  |  |
integer |  | Boolean | Boolean | Boolean | Boolean |  |  |  |
decimal |  | Boolean | Boolean | Boolean | Boolean |  |  |  |
date |  |  |  |  |  | Boolean |  |  |
time |  |  |  |  |  |  | Boolean |  |
text |  |  |  |  |  |  |  | Boolean | Boolean
code |  |  |  |  |  |  |  | Boolean | Boolean

See Also

Concepts

Type Conversion Mechanisms


Boolean (Logical) Operators

Boolean (Logical) Operators

The logical operators can only be used with arguments that can be evaluated to Boolean.

Boolean Operators

As the following table shows, the NOT operator is a unary prefix operator. This means that it takes only one argument and is placed in front of the argument. The AND, OR, and XOR operators are binary infix operators; they take two arguments and are placed between the corresponding arguments.

Operator | Name | Expression | Resulting data type
NOT | Logical negation | NOT bool | bool
AND | Logical and | bool AND bool | bool
OR | Logical or | bool OR bool | bool
XOR | Exclusive logical or | bool XOR bool | bool

See Also

Concepts

Type Conversion Mechanisms


Arithmetic Operators

Arithmetic Operators

This topic contains examples of how to use the type conversion rules for arithmetic operators. The examples illustrate how the operators should be used and the effect of the type conversion that the C/AL compiler performs. The examples have been divided into groups corresponding to the data types in C/AL.

Using Type Conversion Rules for Arithmetic Operators

For a full description of the type conversion rules in C/AL, see Type Conversion Rules for Arithmetic Operators, which provides a full description of all the possible uses of C/AL operators and the resulting data types.

Example 1

This table illustrates type conversion in integer operator expressions.

Operator | Name | Expression | Resulting data type
+ | time addition | time + integer | time
- | time difference | time - time | integer

The time unit is milliseconds. If time is undefined (0T), a run-time error will occur.

Example 2

This table illustrates type conversion in text and code (String) operator expressions.

Operator | Name | Expression | Resulting data type
+ | Concatenation | text + text | text
+ | Concatenation | text + code | text
+ | Concatenation | code + text | text
+ | Concatenation | code + code | code

See Also

Concepts

Type Conversion Mechanisms


Type Conversion Rules for Arithmetic Operators

Type Conversion Rules for Arithmetic Operators

This topic provides a complete overview of type conversion rules for the arithmetic operators.

The Unary Arithmetic Operators

The unary arithmetic operators in C/AL are so-called prefix operators, whose syntax is:

CopyCode image Copy Code
PrefixExpression = PrefixOperator Expression

The following table shows the data types for which the unary operators in C/AL are defined, and the resulting data types.

Unary operator | Option | Integer | Decimal
+ | integer | integer | decimal
- | integer | integer | decimal

The Binary Arithmetic Operators

The following table shows the data types for which the binary arithmetic operators are defined. The binary arithmetic operators in C/AL are all infix operators, that is:

CopyCode image Copy Code
InfixExpression = LeftExpression InfixOperator RightExpression
Operator | Boolean | Char | Option | Integer | Decimal | Date | Time | Text | Code
+ | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes
- | No | Yes | Yes | Yes | Yes | Yes | Yes | No | No
* | No | Yes | Yes | Yes | Yes | No | No | No | No
/ | No | Yes | Yes | Yes | Yes | No | No | No | No
DIV | No | Yes | Yes | Yes | Yes | No | No | No | No
MOD | No | Yes | Yes | Yes | Yes | No | No | No | No

In the table, Yes means that the operator can take at least one operand (left, right, or both) of the given type; No means that the operator cannot be used with the given type.

The following table defines the valid uses of the binary arithmetic operators, and the resulting data types.

Definition of Type Conversion Rules for the "+" Operator

The "+" operator | Boolean | Char | Option | Integer | Decimal | Date | Time | Text | Code
Boolean |  |  |  |  |  |  |  |  |
char |  | integer | integer (C) | integer (C) | decimal (C) |  |  |  |
option |  | integer | integer (C) | integer (C) | decimal (C) |  |  |  |
integer |  | integer (C) | integer (C) | integer (C) | decimal (C) |  |  |  |
decimal |  | decimal (C) | decimal (C) | decimal (C) | decimal (C) |  |  |  |
date |  | date (A) (C) | date (A) (C) | date (A) (C) | date (A) (C) (D) |  |  |  |
time |  | time(B) (C) | time(B) (C) | time(B) (C) | time(B) (C) (D) |  |  |  |
text |  |  |  |  |  |  |  | text | text
code |  |  |  |  |  |  |  | text | code

(A) The operation is not defined for the date 0D.

(B) The operation is not defined for the time 0T.

(C) Overflow may occur.

(D) The operation is not defined if the decimal has a fractional part.


Elements of C/AL Expressions

Elements of C/AL Expressions

All expressions in C/AL are built from the following:

  • Constants

  • Variables

  • Operators

  • Functions

  • Keywords

The topics in this section describe each of these elements.

See Also

Concepts

C/AL Constants
C/AL Variables
C/AL Operators
C/AL Function Calls
C/AL Keywords


C/AL Constants

C/AL Constants

A constant is the simplest type of operand used in C/AL. The value of a constant cannot be changed during the execution of the code. Constants can be defined for each of the simple data types in C/AL.

Note Note

Numbers such as 2,147,483,647 and 999,999,999,999,999.99 cannot be entered in the C/AL editor in this form that uses commas. The commas are only used to increase the legibility when describing large numbers. If you use commas when you enter numbers in the C/AL editor, a compilation error occurs.

Boolean Constant

A Boolean constant can have either the value TRUE or FALSE.

Integer Constant

An integer constant has a value in the range -2,147,483,647 to 2,147,483,647.

Decimal Constant

A decimal constant must contain a decimal point "." (depending on your regional settings) and have at least one digit to the right of the decimal point (for example, the digit "0"). A constant of type decimal can be used to represent decimal numbers between -999,999,999,999,999.99 and 999,999,999,999,999.99 with 18 significant digits.

Date Constant

A date constant is written as six or eight digits followed by the letter "D." The date constant expressing "undefined date" is entered as "0D." The digits specify the date in the format MMDDYY or MMDDYYYY.

Time Constant

A time constant is written as six or nine digits followed by the letter "T." The "undefined time" constant is entered as "0T." The nine digits specify the time in the format HHMMSS[.XXX], that is, a 24 hour format with an optional part specifying thousandths of a second.

Text Constant

A text constant is a character string. Unique IDs are assigned to text constants so that an ID number represents a specific text constant. Examples of text constants are error messages, messages, and warnings.

Examples

The following table shows examples of different types of C/AL constants.

Note Note

The format depends on the regional format that is set on your computer. The examples in the table correspond to a computer with the regional format set to English (United States).

Constant | Description
50000 | Integer constant
-23.7 | Decimal constant
122101D | Date constant (December 21, 2001)
141230T | Time constant (the time 14:12:30)
ABC | Text constant


C/AL Variables

C/AL Variables

C/AL has the following types of variables:

  • User-defined variables

  • System-defined variables

User-defined variables are variables that you define when you create new C/AL code. You can define variables that are global and apply to all functions within an object, such as a codeunit, or you can define variables that are local and apply to a single function in an object. Both types of user-defined variables are local to the object in which they are defined. These variables can be used to store information at run time, and the values can be changed as desired.

System-defined variables are provided by Microsoft Dynamics NAV. These variables are automatically maintained by the system. Some system-defined variables are Rec, xRec, CurrForm, and CurrReport.

At run time, code is executed in functions and triggers, such as in entry-processing code for a table. Before the code is executed, values are automatically assigned to the associated system-defined variables, and the values of these variables can be used in triggers and local functions.

The values of system-defined variables are not updated when the C/AL code is being executed. Instead, the values are updated before the function or trigger is executed.

Note Note

The value in a system-defined variable does not propagate backwards. A user cannot use a system-defined variable to modify the state of the system.

Variable Names

You must follow the following rules and restrictions when you name variables:

  • Variable names must be unique. A codeunit cannot contain two user-defined variables with the same name in the same scope. You can have a local variable and a global variable with the same name, but we do not recommend this.

  • Uppercase and lowercase letters are not distinct. For example, Smith and SMITH refer to the same variable.

  • In C/AL, you can use special characters such as spaces in the name of a variable (an identifier).

  • The maximum length of a variable name is 30 characters.

  • A variable cannot have the same name as a C/AL function or a reserved word. This applies to both uppercase and lowercase spellings. For example, you cannot use BEGIN or begin as a valid variable name.

All characters in your current ANSI character set are valid in variable names except for the following characters:

  • Control characters (ANSI 0-31, 255)

  • The quotation mark character (") (ANSI 34)

Note Note

We do not recommend using characters that are outside the ASCII characters set, 0-127, because they may display differently on different computers.

When you name a variable, you cannot use special characters unless you enclose the variable name in quotation marks, as in "Customer No.". If you do not use double quotes, then the following rules apply:

  • The first character must be one of the following:

    • A letter in the range a…z, A…Z (ASCII 97-122, 65-90)

    • An underscore (ASCII 95)

  • The first character is followed by a maximum of 29 characters, which can be any of the following:

    • A letter in the range a…z, A…Z (ASCII 97-122, 65-90)

    • An underscore (ASCII 95)

    • A digits in the range 0…9 (ASCII 48-57)

You can include one or more special characters in a variable name in C/AL. If you include special characters, then the variable name must be enclosed in quotation marks. In this case, the name can contain any mix of letters, digits, and special characters.

Note Note

The quotation marks are not part of the variable name but are required to successfully compile the codeunit.

Examples

The following examples show valid variable names:

  • Customer

  • StockGroup1

  • "@Vendor"

  • "1st AddressLine"

  • "Purchase/Sales"

  • "Sales in GBP"

  • "Name with Special Characters1Ñ3"

The following examples show incorrect variable names:

  • 34467

  • 23"Tubes

  • Stock Group4

  • "Sale"s in GBP"

  • )-Names

  • END

Initialization

Variables are automatically initialized before C/AL code is executed. A Boolean variable is set to false. Numeric variables are set to the default value zero. Strings (text and code) are initialized to the value '' (an empty string). Date and time variables are set to the undefined time 0T and the undefined date 0D, respectively. Variables of complex data types are also initialized. If a complex data type has multiple components, then each component is initialized to the value that corresponds to the data type for the component.

System-defined variables are automatically handled and initialized. No actions are required by the user before system-defined variables can be used.

Assignment and Type Conversion

You can assign values in the following ways:

  • As parameter assignment, such as FUNCTION(Expression). The data type that results from the evaluation of the expression must correspond to a specific data type or have a data type that can be converted automatically to the correct data type. For more information about evaluation and type conversion in expressions, see Type Conversion in Expressions.

  • By using the assignment operator ":=", such as Variable := Expression. The data type that results from the evaluation of the right side expression must be the same data type as the variable (left operand) or have a data type that can be converted automatically to the data type of the left operand.

Automatic type conversion in assignments takes place when the following events occur:

  • A parameter in a function call does not have the correct data type. For example, this can happen if a function that is supposed to be called with an integer argument is called with a decimal argument.

    Note Note

    If the value cannot be converted, then a run-time error occurs. For example, a run-time error occurs if a function that requires an integer is called with a decimal value of 2.5.

  • The evaluation of the expression on the right side of an assignment operator (:=) results in a data type that differs from the data type of the variable on the left side, and the expression can be converted to the data type of the variable.

Automatic type conversion in assignments can take place between the following numeric data types as long as an overflow does not occur:

  • Char

  • Integer

  • Decimal

Automatic type conversion in assignments can take place between the string data types:

  • Code

  • Text

Text can be automatically converted to BigText, but a BigText variable must be split into smaller parts before it can be converted to text.

The same assignment rules apply for arrays in C/AL. Furthermore, if the left operand in an assignment (the variable) is an array, the dimension or dimensions of the right side expression must correspond to the dimension or dimensions of the variable.

Note Note

The type conversion that takes place in assignments can cause run-time errors even though the data types are convertible. A run-time error can occur in an assignment if the converted value is outside the valid range for the left side variable. Also, a run-time error can occur if the converted value is outside the valid range for a parameter in a function call.

Example 1

The MyVar variable is defined as a one-dimensional array with four text type elements with the maximum length 15. This example shows that a value can be assigned to the second element in the array.

CopyCode image Copy Code
MyVar[2]:= 'Enter your name';

Example 2

In the following example, the Result variable is an Option variable. The Amount and Total variables are both Decimal variables.

CopyCode image Copy Code
Amount := 10;
Total := 4;
...
Result := Amount + Total;

This code can always be compiled, but a run-time error occurs if the result of the right-side expression "Amount + Total" exceeds the range that is permitted by the data type of the left-side Result variable. For an Option variable, the range is the same as the range of an Integer, which is from -2,147,483,647 to 2,147,483,647. A run-time error also occurs if the result of the right-side expression "Amount + Total" is not an integer.

Valid Assignments

The following tables show whether you can assign the value of an expression of a given type to a variable of the same type or to a variable of a different type.

This table shows the numeric data types.

 | Char expression | Option expression | Integer expression | BigInteger expression | Duration expression | Decimal expression
Char variable | Valid | Valid but overflow may occur | Valid but overflow may occur | Valid but overflow may occur | Valid but overflow may occur | Valid but overflow may occur
Option variable | Valid | Valid | Valid except in a FOR statement | Valid but overflow may occur | Valid but overflow may occur | Valid but overflow may occur
Integer | Valid | Valid | Valid | Valid but overflow may occur | Valid but overflow may occur | Valid but overflow may occur
BigInteger variable | Valid | Valid | Valid | Valid | Valid | Valid but overflow may occur
Duration variable | Valid | Valid | Valid | Valid | Valid | Valid but overflow may occur
Decimal variable | Valid | Valid | Valid | Valid but overflow may occur | Valid but overflow may occur | Valid

This table shows the string data types.

 | Text expression | Code expression | BigText expression
Text variable | Valid but overflow may occur | Valid but overflow may occur | Valid but overflow may occur
Code variable | Valid but overflow may occur | Valid but overflow may occur | Valid but overflow may occur
BigText variable | Valid but overflow may occur | Valid but overflow may occur | Valid but overflow may occur
Note Note

You can assign the BigText variable with the BigText functions. For more information, see BigText Data Type.


C/AL Operators

C/AL Operators

Operators can be used in expressions to combine, investigate, and manipulate values and data elements.

C/AL Operators and Meaning

The following table shows the valid operators in C/AL.

C/AL operator | Meaning
. | Fields in records, controls in forms, and reports
( ) | Parentheses
[ ] | Indexing
:: | Scope
+ | Addition
- | Subtraction or negation
* | Multiplication
/ | Division
DIV | Integer division
MOD | Modulus
> | Greater than
>= | Greater than or equal to
< | Less than
<= | Less than or equal to
= | Equal to
<> | Not equal to
IN | In range
AND | Logical conjunction
OR | Logical disjunction
NOT | Logical negation
XOR | Exclusive logical disjunction
.. | Range
@ | Case-insensitive

The "+" and the "-" operators can be used both as unary and binary operators. The "NOT" operator can only be used as a unary operator. All the other operators are binary.

Most of the operators can be used on different data types. The action of these operators may depend upon the data type of the expression that they are used on.

Example 1

In this example, the "+" operator is used as a binary operator.

CopyCode image Copy Code
number + number

This returns the sum of the numbers, that is, a result of type number.

Example 2

In this example, the "+" operator is used as a binary operator.

CopyCode image Copy Code
string + string

This returns the concatenation of the strings, that is, a result of the type string.

Example 3

In this example, the "+" operator is used as a unary operator to indicate sign.

CopyCode image Copy Code
+34545

Operator Hierarchy

Operators are organized in a hierarchy that determines the order in which the operands in a given expression are evaluated. The following list shows the order of precedence of the C/AL operators:

  1. .(fields in records), [] (indexing), () (parentheses), :: (scope)

  2. NOT, - (unary), + (unary)

  3. *,/,DIV, MOD, AND, XOR

  4. +, -, OR

  5. >, <. >=, <=, = <>, IN

  6. .. (range)

Example 1

CopyCode image Copy Code
2 + 3 * 4

This expression evaluates to 14.

Example 2

CopyCode image Copy Code
(2 + 3) * 4

This expression evaluates to 20.


C/AL Function Calls

C/AL Function Calls

C/AL contains a number of functions that can be used for different purposes, such as string handling, text formatting, database handling, and so on. Some of these functions can use different parameters.

Parameters

In a function call, the parameters are separated by commas, and the optional parameters may be omitted starting from the right. For example, this means that if a function has three optional parameters, then you cannot omit the second parameter without omitting the third parameter.

You can specify that a parameter is passed to a function by value or by reference.

  • If a parameter is passed by value, then a copy of the variable is passed to the function. Any changes that the function makes to the value of the variable are local changes that affect only the copy, not the variable itself.

  • If a parameter is passed by reference, then a reference to the variable is passed to the function. The function can change the value of the variable itself.

For more information about how to specify that a parameter is passed by value or by reference, see How to: Add a Function to a Codeunit.

Example 1

The following shows the syntax for a function.

CopyCode image Copy Code
FUNCTION([Optional1] [, Optional2] [, Optional3])

The function with the syntax above can be called by using the following code.

CopyCode image Copy Code
FUNCTION(Optional1, Optional2)

This function cannot be called by using the following code.

CopyCode image Copy Code
FUNCTION(, Optional2, Optional3)

Example 2

ABS is an example of a C/AL function with a fixed number of parameters (1).

CopyCode image Copy Code
Value := -1033; //A negative integer value
PositiveValue := ABS(Value); //Calculate the positive value 1033

Example 3

The function DMY2DATE is an example of a function that can be called with a variable number of parameters.

CopyCode image Copy Code
NewDate := DMY2DATE(5, 11, 1992); //Returns the date November 5, 1992

Depending on the use of the DMY2DATE function, 1, 2, or 3 parameters can be passed to the function because the second and third parameters are optional. When the second and third parameters are not used, values from the system date are used as default.

Return Values

A function can return a value. For more information about how to specify that a function has a return value, see How to: Add a Function to a Codeunit.

Example 1

You can assign the return value of a function to a variable.

CopyCode image Copy Code
ReturnVal := MyFunction(Param1);

Example 2

In this example, MyFunction returns a Boolean value. You can use the return value in a conditional statement.

CopyCode image Copy Code
IF (MyFunction(Param1)) THEN
  <Statement1>
ELSE
  <Statement2>


C/AL Keywords

C/AL Keywords

Keywords are predefined reserved words that have special meanings to the compiler. They cannot be used as variable or function names in your application code.

Keywords are one of the elements that make up C/AL statements.

The following table lists the keywords in C/AL.

Keyword | For more information
ASSERTERROR | C/AL ASSERTERROR Statements
BEGIN | C/AL Compound Statements
CASE | C/AL Conditional Statements
DO | C/AL Repetitive Statements
DOWNTO | C/AL Repetitive Statements
ELSE | C/AL Conditional Statements
END | C/AL Compound Statements
EXIT | C/AL Repetitive Statements
FOR | C/AL Repetitive Statements
IF | C/AL Conditional Statements
OF | C/AL Conditional Statements
REPEAT | C/AL Repetitive Statements
THEN | C/AL Conditional Statements
TO | C/AL Repetitive Statements
UNTIL | C/AL Repetitive Statements
WHILE | C/AL Repetitive Statements
WITH | C/AL WITH Statements

See Also

Concepts

C/AL Reserved Words
Elements of C/AL Expressions


C/AL Simple Statements

C/AL Simple Statements

C/AL simple statements are single-line statements that are executed sequentially and do not alter the flow of execution of code. The following are the types of simple statements in C/AL:

  • C/AL Assignment Statements

  • C/AL Function Statements

  • C/AL ASSERTERROR Statements

  • C/AL WITH Statements


C/AL Assignment Statements

C/AL Assignment Statements

Assignment statements assign a value to a variable. The value that you assign to the variable is a C/AL expression. It can be a constant or a variable, or it can be made up of multiple elements of C/AL expressions. If you use a function call as the value to assign to a variable in an assignment statement, then the value that is assigned is the return value of the function.

You use the ":=" operator for assignment statements.

Example

The following example assigns a constant integer value to an integer variable that you have defined.

CopyCode image Copy Code
Count := 1;

Example

The following example assigns a value that is made up of a constant, an operator, and a variable.

CopyCode image Copy Code
Amount := 2 * Price;

Example

The following example assigns the return value of the OPEN Function (File) to a Boolean variable that you have defined.

CopyCode image Copy Code
OK := TestFile.OPEN('C:\temp\simple.xml');

The return value of the OPEN function is optional. If you do not handle the return value in your code, then a run-time error occurs when a function returns FALSE. The following example causes a run-time error if the file C:\temp\simple.xml cannot be opened.

CopyCode image Copy Code
TestFile.OPEN('C:\temp\simple.xml');

You can handle the return value is by using an IF-THEN statement.

CopyCode image Copy Code
IF TestFile.OPEN('C:\temp\simple.xml') THEN BEGIN
  // continue running
ELSE
  ERROR(Text001);

See Also

Concepts

C/AL Simple Statements


C/AL Function Statements

C/AL Function Statements

You use function statements to execute either built-in system functions or user-defined functions. Function calls may include parameters, which are passed to the function.

If you assign the return value of a function call to a variable, then you use the function statement as part of an assignment statement.

Triggers are C/AL elements that consist of an event and a function. Triggers execute a function when a certain event occurs. For more information, see the following topics:

  • Triggers Overview

  • Triggers

Example

The following example calls the INIT Function (Record) on a record variable. This example requires that you create the following variable.

Name | DataType | Subtype
CustomerRecord | Record | Customer
CopyCode image Copy Code
CustomerRecord.INIT;

Example

The following example calls the CALCDATE Function (Date) and assigns the return value to a variable. The CALCDATE function has two parameters. This example uses the DateExpression and ReferenceDate variables in the function call. The values of the variables are passed to the CALCDATE function.

This example requires that you create the following variables.

Name | DataType | Length
DateExpression | Text | 30
ReferenceDate | Date |
NewDate | Date |
CopyCode image Copy Code
DateExpression := '<-7D>'
ReferenceDate := 112509D;
NewDate := CALCDATE(DateExpression, ReferenceDate);

After you run the code in this example, the NewDate variable denotes the date November 18, 2009.

See Also

Concepts

C/AL Functions
Triggers
C/AL Simple Statements


C/AL ASSERTERROR Statements

C/AL ASSERTERROR Statements

You use ASSERTERROR statements in test functions to test how your application behaves under failing conditions. The ASSERTERROR keyword specifies that an error is expected at run time in the statement that follows the ASSERTERROR keyword.

If a simple or compound statement that follows the ASSERTERROR keyword results in an error, then execution successfully continues to the next statement in the test function. You can get the error text of the statement by using the GETLASTERRORTEXT Function.

If a statement that follows the ASSERTERROR keyword does not result in an error, then the ASSERTERROR statement itself fails with the following error and the test function that is running produces a FAILURE result:

TestAsserterrorFail: FAILURE

An error was expected inside an ASSERTERROR statement.

Example

To create a test function to test the result of a failure of a CheckDate function that you have defined, you can use the following code. This example requires that you create a function called CheckDate to check whether the date is valid for the customized application and that you create the following text constant and variables.

Text constant | ENU value
Text001 | 'The date is outside the valid date range.'
Name | DataType
InvalidDate | Date
InvalidDateErrorMessage | Text
CopyCode image Copy Code
InvalidDate := 010184D;
InvalidDateErrorMessage := Text001;
ASSERTERROR CheckDate(InvalidDate);
IF GETLASTERRORTEXT <> InvalidDateErrorMessage THEN
  ERROR('Unexpected error: %1', GETLASTERRORTEXT);

See Also

Tasks

How to: Create Test Codeunits and Test Functions

Concepts

Testing the Application
C/AL Keywords


C/AL WITH Statements

C/AL WITH Statements

The following syntax shows a WITH-DO statement.

CopyCode image Copy Code
WITH <Record> DO
  <Statement>

When you work with records, addressing is created as record name, dot (period), and field name:

<Record>.<Field>

If you work continuously with the same record, then you can use WITH statements. When you use a WITH statement, you only specify the record name once.

Within the scope of <Statement>, fields in <Record> can be addressed without having to specify the record name.

You can nest several WITH statements. If you have identical names, then the inner WITH statement overrules the outer WITH statement.

Example

This example shows two ways to write the same code that creates a record variable that you can commit later.

Create the following variable.

Variable | Data type | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerRec."No." := '1234';
CustomerRec.Name := 'Windy City Solutions';
CustomerRec."Phone No." := '555-444-333';
CustomerRec.Address := '1241 Druid Avenue';
CustomerRec.City := 'Windy City';
MESSAGE('A variable has been created for this customer.');

The following example shows another way to create a record variable that you can commit later

CopyCode image Copy Code
WITH CustomerRec DO BEGIN
  "No." := '1234';
  Name := 'Windy City Solutions';
  "Phone No." := '555-444-333';
  Address := '1241 Druid Avenue';
  City := 'Windy City';
  MESSAGE('A variable has been created for this customer.');
END;

Programming Conventions

Within WITH-DO blocks, do not repeat the name of the object with the member variable or function.

If you nest a WITH-DO block within another explicit or implicit WITH-DO block, then the WITH-DO block that you create within another WITH-DO block must always be attached to a variable of the same type as the variable that is attached to the surrounding WITH-DO block. Otherwise, it can be difficult to see what variable that a member variable or function refers to. For example, implicit WITH-DO blocks exist in table objects and in forms that have been attached to a record.

Example

The following example demonstrates nested WITH-DO blocks. Both WITH-DO blocks are attached to a Customer Ledger Entry record variable.

CopyCode image Copy Code
WITH CustLedgEntry DO BEGIN
  INSERT;
  ...;
  WITH CustLedgEntry2 DO BEGIN
    INSERT;
    ...;
  END;
END;

Incorrect Example

The following example demonstrates incorrect code in which you cannot directly tell which record variable that the MyField field refers to.

CopyCode image Copy Code
WITH CustLedgEntry DO BEGIN
  ...;
  WITH VendLedgEntry DO BEGIN
    MyField := <Some Value>;
    ...;
  END;
END;

See Also

Concepts

C/AL Compound Statements
C/AL Conditional Statements
C/AL Repetitive Statements


C/AL Control Statements

C/AL Control Statements

All the C/AL programs that you create consist of one or more statements, which are executed sequentially in top-down order. However, you will often need to control the direct top-down flow of the execution. One or more statements may have to be repeated more than once, or you may have to make the execution of a certain statement conditional. To do this, you use control structures.

The control structures in C/AL are divided into the following main groups:

  • C/AL Compound Statements

  • C/AL Conditional Statements

  • C/AL Repetitive Statements


C/AL Compound Statements

C/AL Compound Statements

A compound statement is one type of control structure in C/AL.

Using Compound Statements

In some cases, the C/AL syntax only allows you to use a single statement. If however you have to execute more than one simple statement, the statements can be written as a compound statement by enclosing the statements between the BEGIN and END keywords.

CopyCode image Copy Code
BEGIN
  <Statement 1>;
  <Statement 2>;
  ..
  <Statement n>;
END

The individual statements are separated by a semicolon. In C/AL, a semicolon is used to separate statements and not, as in other programming languages, as a terminator symbol for a statement. Nevertheless, an extra semicolon before an END does not cause an error because it is interpreted by the compiler as an empty statement.

Blocks

The BEGIN-END structure is also called a block. Blocks can be very useful in connection with the other control structures in C/AL.

When BEGIN follows THEN, ELSE, or DO, it should be on the same line and preceded by one space character.

Example

CopyCode image Copy Code
IF (x = y) AND (a = b) THEN BEGIN
  x := a;
  y := b;
END;

Example

CopyCode image Copy Code
IF (xxx = yyyyyyyyyy) AND
   (aaaaaaaaaa = bbb)
THEN BEGIN
  x := a;
  x := y;
  a := y;
END ELSE BEGIN
  y := x;
  y := a;
END;

See Also

Concepts

C/AL Conditional Statements
C/AL Repetitive Statements
C/AL WITH Statements


C/AL Conditional Statements

C/AL Conditional Statements

A conditional statement is one type of control structure in C/AL.

You use conditional statements to specify a condition and one or more commands to execute if the condition is evaluated as true or false. There are two types of conditional statements in C/AL:

  • IF-THEN-ELSE, where there are two choices.

  • CASE, where there are more than two choices.

IF-THEN ELSE Statements

IF-THEN-ELSE statements have the following syntax.

CopyCode image Copy Code
IF <Condition> THEN
  <Statement1>
[ELSE
  <Statement2>]

If <Condition> is true, then <Statement1> is executed. If <Condition> is false, then <Statement2> is executed.

The square brackets around ELSE <Statement2> mean that this part of the statement is optional. The ELSE statement is used when different actions are executed depending on how <Condition> is evaluated.

You can build more complex control structures by nesting IF-THEN-ELSE statements. The following example is a typical IF-THEN-ELSE statement.

CopyCode image Copy Code
IF <Condition1> THEN
  IF <Condition2> THEN
    <Statement1>
  ELSE
    <Statement2>

If <Condition1> is false, then nothing is executed. If <Condition1> and <Condition2> are both true, then <Statement1> is executed. If <Condition1> is true and <Condition2>is false, then <Statement2> is executed.

Note Note

A semicolon preceding an ELSE statement is not allowed.

Reading several nested IF-THEN-ELSE statements can be quite confusing but a general rule is that an ELSE statement belongs to the last IF statement that lacks an ELSE statement.

Programming Conventions

IF and THEN should be on the same line. ELSE should be on a separate line.

If there are many or long expressions, THEN should be on a new line and be aligned with IF.

When you write IF expressions with THEN and ELSE parts, write them so that the THEN consequence is more probable than the ELSE one.

If the last statement in the THEN part of an IF-THEN-ELSE statement is an EXIT or an ERROR, do not continue with an ELSE statement.

Example

CopyCode image Copy Code
IF x = y THEN
  x := x + 1
ELSE
  x := -x - 1;

Example

CopyCode image Copy Code
IF (xxxxxxxxxx = yyy) AND
   (aaa = bbbbbbbbbb)
THEN
  x := a
ELSE
  y := b;

Example

CopyCode image Copy Code
IF x <> y THEN
  EXIT(TRUE);
x := x * 2;
y := y - 1;

Incorrect Example

CopyCode image Copy Code
IF x < y THEN
  EXIT(TRUE)
ELSE BEGIN
  x := x * 2;
  y := y - 1;
END;

Example

The following example shows an IF-THEN statement without the optional ELSE statement.

CopyCode image Copy Code
IF Amount < 1000 THEN
  Total := Total + Amount;

Example

The following example shows a nested IF-THEN-ELSE statement.

CopyCode image Copy Code
...
IF Amount < 1000 THEN BEGIN
  IF I > J THEN
    Max := I
  ELSE
    Max := J;
  Amount := Amount * Max;
END
ELSE
...

CASE Statements

CASE statements have the following syntax.

CopyCode image Copy Code
CASE <Expression> OF
  <Value set 1>:
    <Statement 1>;
  <Value set 2>:
    <Statement 2>;
...
...
  <Value set n>:
    <Statement n>;
[ELSE
  <Statement n+1>]
END;

In this definition, <Expression> cannot be a record and <Value set> must be an expression or a range.

CASE statements are also called multiple option statements and are typically used when you must choose between more than two different actions. The function of the CASE statement is as follows:

  • The <Expression> is evaluated, and the first matching value set executes the associated statement, if there is one.

  • If no value set matches the value of the expression and the optional ELSE part has been omitted, then no action is taken. If the optional ELSE part is used, then the associated statement is executed.

The data type of the value sets must be the same as the data type of <Expression> or at least be convertible to the same data type.

In most cases, the data type of the value sets are converted to the date type of the evaluated expression. The only exception is if the evaluated expression is a Code variable. If the evaluated expression is a Code variable, then the value sets are not converted to the Code data type.

Note Note

In previous versions of Microsoft Dynamics NAV, the value sets are always converted to the data type of the evaluated expression, even if that data type is Code.

Note Note

This type conversion can cause an overflow at run time if the resulting data type cannot hold the values of the datasets.

For more information about Code variables, see Code Data Type.

Programming Conventions

When you use a CASE statement, indent the value sets by two character spaces. If you have two or more value sets on the same line, then separate them by commas with no spaces. The last value set on a line is immediately followed by a colon with no preceding space. The action starts on the line after the value set and is further indented by two character spaces. If there is a BEGIN, then it should be placed on a separate line unless it follows ELSE. If a BEGIN follows an ELSE, then it should be on the same line as ELSE.

If there are more than two alternatives, use a CASE statement. Otherwise, use an IF-THEN-ELSE statement.

Example

CopyCode image Copy Code
CASE Field OF
  Field::A:
    BEGIN
     x := x + 1;
     y := -y - 1;
    END;
  Field::B:
    x := y;
  Field::C,Field::D:
    y := x;
  ELSE BEGIN
    y := x;
    a := b;
  END;
END

Example

The following C/AL code prints various messages depending on the value of Number. If the value of Number does not match any of the entries in the CASE structure, then the ELSE entry is used as the default.

CopyCode image Copy Code
CASE Number OF
  1,2,9:
    MESSAGE('1, 2, or 9.');
  10..100:
    MESSAGE('In the range from 10 to 100.');
  ELSE
    MESSAGE('Neither 1, 2, 9, nor in the range from 10 to 100.');
END

Example

The following C/AL code shows how value sets in a CASE statement are evaluated in Microsoft Dynamics NAV 2009 and in previous versions of Microsoft Dynamics NAV. This example requires that you create the following variable.

Variable | Data type
MyCode | Code
CopyCode image Copy Code
MyCode := 'ABC';
CASE MyCode OF
  'abc':
    MESSAGE('displays in previous versions of Microsoft Dynamics NAV');
  'def':
    MESSAGE('does not display;);
ELSE
  MESSAGE('displays in Microsoft Dynamics NAV 2009');

If you run this example on a previous version of Microsoft Dynamics NAV, then the value set 'abc' is converted to the data type of the evaluated expression MyCode. When it is converted to a Code data type, it is also converted to uppercase. In Microsoft Dynamics NAV 2009, the value set 'abc' is not converted because the evaluated expression MyCode is a Code variable.

See Also

Concepts

C/AL Compound Statements
C/AL Repetitive Statements
C/AL WITH Statements


C/AL Repetitive Statements

C/AL Repetitive Statements

A repetitive statement is also known as a loop. The following table shows the looping mechanisms in C/AL.

Looping mechanism | Description
FOR | Repeats the inner statement until a counter variable equals the maximum or minimum value specified.
WHILE | Repeats the inner statement as long as the specified condition is TRUE. The statement in a loop of this type is repeated 0 or more times.
REPEAT | Repeats the inner statements until the specified conditions evaluate to TRUE. The statements in a loop of this type are always executed at least once.

FOR-TO and FOR-DOWNTO Control Structure

The following syntax shows the FOR-TO and FOR-DOWNTO statement.

CopyCode image Copy Code
FOR <Control Variable> := <Start Number> TO <End Number> DO
  <Statement>

The data type of <Control Variable>, <Start Number>, and <End Number> must be Boolean, number, time, or date.

Use FOR statements when you want to execute code a specific number of times.

Use a control variable to control the number of times that the code is executed. The control variable can be increased or decreased by one, depending on whether TO or DOWNTO is used.

Note Note

When the FOR statement is executed, <Start Number> and <End Number> are converted to the same data type as <Control Variable> if necessary. This type conversion can cause a run-time error.

When using a FOR-TO loop, the <Statement> will not be executed if the <Start Number> is greater than the end value. When using a FOR-DOWNTO loop, the <Statement> will not be executed if the <Start Number> is less than the end value.

Note Note

If the value of the control variable is changed inside the FOR loop, then the behavior is not predictable. Furthermore, the value of the control variable is undefined outside the scope of the FOR loop.

Example 1

Create the following variable.

Variable | Data type
Count | Integer

The following code initiates a FOR loop that uses the integer control variable named Count.

CopyCode image Copy Code
FOR Count := 1000 TO 100000000000000 DO

When this statement is executed, a run-time error occurs because the start and end values are converted to the same data type as the Count control variable. Count has been declared as an integer variable. The end number 100000000000000 is outside the valid range for integers, and an error occurs.

Example 2

The following example shows how to nest FOR statements.

Create the following variables.

Variable | Data type
I | Integer
J | Integer

Set the Dimensions property of variable A to 5;7.

The following FOR statements could be used to initialize every element in a 5x7 array with the value 23.

CopyCode image Copy Code
FOR I := 1 TO 5 DO
  FOR J := 1 TO 7 DO
    A[I,J] := 23;

WHILE-DO Control Structure

The following syntax shows the WHILE-DO statement.

CopyCode image Copy Code
WHILE <Condition> DO
  <Statement>

If <Condition> is TRUE, then <Statement> is executed repeatedly until <Condition> becomes FALSE. If <Condition> is FALSE from the start, then <Statement> is never executed.

The WHILE DO statement can be used when some code should be repeated as long as an expression is TRUE.

Programming Conventions

When there is only one condition, put WHILE and DO on the same line. Put the statements on separate lines and indented by two spaces.

When there are multiple conditions, put the conditions on separate lines and indented by two spaces and put DO on a separate line that is aligned with WHILE.

Example

CopyCode image Copy Code
WHILE <expr> DO
  <Statement>;

Example

CopyCode image Copy Code
WHILE <expr> DO BEGIN
  <Statement>;
  <Statement>;
END;

Example

CopyCode image Copy Code
WHILE <expr> AND
      <expr> AND
      <expr>
DO BEGIN
  <Statement>;
  <Statement>;
END;

Example

Create the following variable.

Variable | Data type
I | Integer

The following C/AL code increases the variable I until it equals 1000 and displays a message when it is finished.

CopyCode image Copy Code
WHILE I < 1000 DO
  I := I + 1;
Message(format(I));

REPEAT-UNTIL Control Structure

The following syntax shows the REPEAT-UNTIL statement.

CopyCode image Copy Code
REPEAT
  <Statements> UNTIL <Condition>

<Statements> is executed repeatedly until <Condition> is TRUE.

The REPEAT UNTIL control structure is similar to the WHILE control structure. The difference is that because the REPEAT UNTIL statement is executed from left to right, the <Statements> is always executed at least once, no matter what the <Condition> is evaluated to. This contrasts with the WHILE control structure, which performs the evaluation before the <Statement> is executed. In the WHILE control structure, if the first evaluation of <Condition> returns FALSE, then no statements are executed.

Programming Conventions

Always put REPEAT on a separate line.

Example

CopyCode image Copy Code
IF x < y THEN BEGIN
  REPEAT
    x := x + 1;
    a := a - 1;
  UNTIL x = y;
  b := x;
END;

Example

Create the following variables.

Variable | Data type | Subtype
Count | Integer |
Customer | Record | Customer
CopyCode image Copy Code
Count := 0;
IF Customer.FIND('-') THEN
REPEAT
  Count := Count + 1;
UNTIL Customer.NEXT <= 0;
Message(’The Customer table contains %1 records.’,Count);

This code uses a REPEAT-UNTIL loop to count the number of entries in the Customer table. The FIND function finds the first entry in the table. Each time NEXT is called, it steps one record forward. When NEXT equals 0, there are no more entries in the table. The loop is exited, and a message displays how many entries were found.

EXIT Statement

The EXIT statement is used to control the flow of the execution. The following syntax shows an EXIT statement.

CopyCode image Copy Code
EXIT([<Value>])

An EXIT statement is used to interrupt the execution of a C/AL trigger. The interruption takes place even when the code is executed inside a loop or a similar structure. The EXIT statement is also used when a local function should return a value.

Using EXIT without a parameter in a local function corresponds to using the parameter value 0. The C/AL function will return the value 0 or '' (empty string).

A compile-time error occurs if EXIT is called with a return parameter from either of the following:

  • System-defined triggers

  • Local functions that do not return a value

Example

The following example shows the use of the EXIT statement in a local function. Assume that the IF statement is used to detect an error. If the error condition is met, then execution is stopped and the local function returns the error code 1.

CopyCode image Copy Code
FOR I := 1 TO 1000 DO BEGIN
  IF Amount[I] < Total[I] THEN
    EXIT(1);
  A[I] := Amount[I] + Total[I];
END;

See Also

Concepts

C/AL Compound Statements
C/AL Conditional Statements
C/AL WITH Statements


C/AL Comments

C/AL Comments

You can insert comments about your C/AL code or comment out parts of your code to prevent execution. The following are the two ways to insert comments in C/AL:

  • Use "//" to insert a single line comment. When the "//" symbol is encountered in your code, the rest of the line is interpreted as a comment.

  • Use "{" and "}" to mark the beginning and end, respectively, of a block of comments.

You can nest any number of comments. In such cases, the comment runs from the first comment start to the last comment end.

Example 1

CopyCode image Copy Code
{
This is a sample comment which is ignored by the C/AL compiler
}

Example 2

CopyCode image Copy Code
// This is also a sample comment which is ignored by the C/AL compiler

Example 3

CopyCode image Copy Code
{ This comment { is partly inside } another comment }

Example 4

This example shows what you should not do.

CopyCode image Copy Code
A := 34;
B := 56;      {******************
C := 345;      * Don’t do this! *
D := 781;      ******************}

Because the comment is to the right of the C/AL statements, the system assumes that the third and fourth lines are part of the comment. That is, only A and B are assigned values, while C and D are not. Instead you should use single line comments.

CopyCode image Copy Code
A := 34;
B := 56;       //*******************
C := 345;      //* Do it this way! *
D := 781;      //*******************


System-Defined Variables

System-Defined Variables

C/SIDE automatically declares and initializes a number of variables that you can use when you develop applications. The following table describes the system-defined variables.

System-defined variable | Comments
Rec | When a record is modified, this variable specifies the current record, including the changes that are made.
xRec | When a record is modified, this variable specifies the original values of the record, before the changes.
CurrForm | This variable specifies the current form. You can access the controls of the form through this variable and set the dynamic properties of the form and its controls.
CurrReport | This variable specifies the current report.
RequestOptionsForm | This variable specifies the request options form for the current report.
CurrFieldNo | This variable specifies the field number of the current field in the current form. Retained for compatibility reasons.

In addition, some triggers, such as the OnFormat trigger of a control, have a parameter that is defined as a local variable.

Example

The following example shows how to use the Rec and xRec pair of records.

In an application, data is stored in two tables, a header table and a line table. The header table contains general information about, for example, sales orders, while the line table contains the specific order lines. The form that you use to enter information into the header table has fields that contain the customer’s address. These fields are related to the Customer table, and can be filled by using a lookup function in the field that establishes the relationship. In the header table, only the customer number is stored, and the other fields with customer information, such as name and address, are retrieved from the Customer table when the Customer No. field is validated.

In some situations, the user should be able to change the customer number, and in other situations the user should not be able to change it. If the order has already been shipped, for example, the user should not be able to change the customer number. If there is an incorrect number on an order that has not been processed completely, the user should be able to correct the error.

You could use the Rec and xRec variables to design your application in the following way:

  • When validating the customer number field, check whether the order has shipped.

  • If the order has shipped, compare the customer number fields in the xRec and Rec records. If they differ, reject the change.


Essential C/AL Functions

Essential C/AL Functions

Although there are more than 100 functions in C/AL, there are several functions that you will use more often than the others. This does not mean that the rest of the functions are obsolete or that you will never use them. However, it does mean that if you are very familiar with this small set of essential functions, you will be able to accomplish many tasks when you are programming in C/AL. When you need to add more specialized functionality to your applications, you can familiarize yourself with more of the functions.

The topics in this section describe the most common C/AL functions. For more details about all of the C/AL functions, see C/AL Functions.

See Also

Concepts

GET, FIND, and NEXT Functions
SETCURRENTKEY, SETRANGE, SETFILTER, GETRANGEMIN, and GETRANGEMAX Functions
INSERT, MODIFY, MODIFYALL, DELETE and DELETEALL Functions
LOCKTABLE Function
CALCFIELDS, CALCSUMS,FIELDERROR, FIELDNAME, INIT, TESTFIELD, and VALIDATE Functions
Progress Windows, MESSAGE, ERROR and CONFIRM Functions
STRMENU Function


GET, FIND, and NEXT Functions

GET, FIND, and NEXT Functions

The following functions are used to search for records:

  • GET

  • FIND

  • NEXT

These functions are some of the most commonly used C/AL functions. When you search for records, it is important to know the difference between GET and FIND and to know how to use FIND and NEXT in conjunction.

GET Function

GET retrieves one record based on values of the primary key fields.

GET has the following syntax.

CopyCode image Copy Code
[Ok :=] Record.GET([Value],...)

For example, if the No. field is the primary key of the Customer table and if you have created a Record variable called CustomerRec that has a Subtype of Customer, then you can use GET in the following way:

CopyCode image Copy Code
CustomerRec.GET('4711');

The result is that the record of customer 4711 is retrieved.

GET produces a run-time error if it fails and the return value is not checked by the code. In the preceding example, the actual code that you write should be similar to the following.

CopyCode image Copy Code
IF CustomerRec.GET('4711') THEN
.... // Do some processing.
ELSE
.... // Do some error processing.

GET searches for the records, regardless of the current filters, and it does not change any filters. GET always searches through all the records in a table.

FIND Function

FIND locates a record in a C/SIDE table based on the values stored in the keys.

FIND has the following syntax.

CopyCode image Copy Code
Ok := Record.FIND([Which])

The important differences between GET and FIND are the following:

  • FIND uses the current filters.

  • FIND can be instructed to look for records where the key value is equal to, greater than, or smaller than the search string.

  • FIND can find the first or the last record, depending on the sort order defined by the current key.

When you are developing applications in a relational database, there are often one-to-many relationships defined between tables. An example could be the relationship between an Item table, which registers items, and a Sales Line table, which registers the detailed lines from sales orders. One 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. You would not want an item record to be deleted as long as there are still open sales orders that include the item. You can use FIND to check for open sales orders.

The OnDelete trigger of the Item table includes the following code that illustrates using FIND.

CopyCode image Copy Code
SalesOrderLine.SETCURRENTKEY(Type,"No.");
SalesOrderLine.SETRANGE(Type,SalesOrderLine.Type::Item);
SalesOrderLine.SETRANGE("No.","No.");
IF SalesOrderLine.FIND('-') THEN
ERROR(Text001,TABLECAPTION,"No.",SalesOrderLine."Document Type");

NEXT Function

NEXT is often used with FIND to step through the records of a table.

NEXT has the following syntax.

CopyCode image Copy Code
Steps := Record.NEXT([Steps])

In the following example, FIND is used to go to the first record of the table. NEXT is used to step through every record, until there are no more. When there are no more records, NEXT returns 0 (zero).

CopyCode image Copy Code
FIND('-');
REPEAT
// process record
UNTIL NEXT = 0;


SETCURRENTKEY, SETRANGE, SETFILTER, GETRANGEMIN, and GETRANGEMAX Functions

SETCURRENTKEY, SETRANGE, SETFILTER, GETRANGEMIN, and GETRANGEMAX Functions

The following functions are used to filter records in a table:

  • SETCURRENTKEY

  • SETRANGE

  • SETFILTER

  • GETRANGEMIN

  • GETRANGEMAX

These functions are some of the most commonly used C/AL functions. They set limits on the value of one or more specified fields, so that only a subset of the records are displayed, modified, deleted, and so on.

SETCURRENTKEY Function

SETCURRENTKEY selects a key for a record and sets the sort order that is used for the table in question.

SETCURRENTKEY has the following syntax.

CopyCode image Copy Code
[Ok :=] Record.SETCURRENTKEY(Field1, [Field2],...)

When you use SETCURRENTKEY the following rules apply:

  • Inactive fields are ignored.

  • When searching for a key, the first occurrence of the specified field(s) is selected. This means the following:

    • If you specify only one field as a parameter when you call SETCURRENTKEY, the key that is actually selected may consist of more than one field.

    • If the field that you specify is the first component of several keys, the key that is selected may not be the key that you expect.

    • If no keys can be found that include the field(s) that you specify, the return value is FALSE. If you do not test the return value, a run-time error occurs. If you do test the return value, the program will continue to run even though no key was found.

SETRANGE Function

SETRANGE sets a simple filter on a field.

SETRANGE has the following syntax.

CopyCode image Copy Code
Record.SETRANGE(Field [,From-Value] [,To-Value]);

In the following example, SETRANGE filters the Customer table by selecting only those records where the No. field has a value between 10000 and 90000.

CopyCode image Copy Code
Customer.SETRANGE("No.",'10000','90000');

When you use SETRANGE the following rules apply:

  • SETRANGE removes any filters that were set previously and replaces them with the From-Value and To-Value parameters that you specify.

  • If you use SETRANGE without setting the From-Value and To-Value parameters, the function removes any filters that are already set.

  • If you only set the From-Value, the To-Value is set to the same value as the From-Value.

SETFILTER Function

SETFILTER sets a filter in a more general way than SETRANGE.

SETFILTER has the following syntax.

CopyCode image Copy Code
Record.SETFILTER(Field, String [, Value], ...];

Field is the name of the field on which you want to set a filter. String is the filter expression. String may contain placeholders, such as %1 and %2, to indicate where to insert the Value parameter(s) in a filter expression.

The following example selects records where the value of No. is larger than 10000 and not equal to 20000.

CopyCode image Copy Code
Customer.SETFILTER("No.", '>10000 & <> 20000');

If the variables Value1 and Value2 have been assigned "10000" and "20000" respectively, then you can use the following statement to create the same filter.

CopyCode image Copy Code
Customer.SETFILTER("No.",'>%1&<>%2',Value1, Value2);

GETRANGEMIN Function

GETRANGEMIN retrieves the minimum value of the filter range that is currently applied to a field.

GETRANGEMIN has the following syntax.

CopyCode image Copy Code
Record.GETRANGEMIN(Field);

A run-time error occurs if the filter that is currently applied is not a range. For example, you can set a filter as follows.

CopyCode image Copy Code
Customer.SETFILTER("No.",'10000|20000|30000');

With this filter, the following code fails because the filter is not a range.

CopyCode image Copy Code
BottomValue := Customer.GETRANGEMIN("No.");

GETRANGEMAX Function

GETRANGEMAX retrieves the maximum value of the filter range that is currently applied to a field.

GETRANGEMAX has the following syntax.

CopyCode image Copy Code
Value := Record.GETRANGEMAX(Field)


INSERT, MODIFY, MODIFYALL, DELETE and DELETEALL Functions

INSERT, MODIFY, MODIFYALL, DELETE and DELETEALL Functions

The following functions maintain the database by adding, modifying, and removing records:

  • INSERT

  • MODIFY

  • MODIFYALL

  • DELETE

  • DELETEALL

These functions are some of the most commonly used C/AL functions.

Some of these functions return an optional Boolean value that indicates whether the function succeeded. If you do not handle the return value in your code, a run-time error occurs when a function returns FALSE. If you handle the return value by testing its value in an IF statement, no error will occur, and you must take corrective action in the code.

INSERT Function

INSERT inserts a record in a table.

INSERT has the following syntax.

CopyCode image Copy Code
[Ok :=] Record.INSERT([RunTrigger])

The following example inserts a new record, with the No. and Name fields specified in the assigned values, while other fields will have their default values. If the No. field is the primary key of the Customer table, then the record will be inserted in the Customer table unless the table already contains a record with the same primary key. In this case you receive an error message because the return value is not tested.

This example requires that you create the following variable.

Variable | Data type | Subtype
Customer | Record | Customer
CopyCode image Copy Code
Customer.INIT;
Customer."No." := '4711';
Customer.Name := 'Andrew Dixon';
Customer.INSERT;

MODIFY Function

MODIFY modifies a record that already exists.

MODIFY has the following syntax.

CopyCode image Copy Code
[Ok :=] Record.MODIFY([RunTrigger])

MODIFY returns an optional Boolean value. It returns TRUE if the record to be modified exists; otherwise, it returns FALSE.

The following example changes the name of customer 4711 to Richard Roe. This example requires that you create the following variable.

Variable | Data type | Subtype
Customer | Record | Customer
CopyCode image Copy Code
Customer.GET('4711');
Customer.Name := 'Richard Roe';
Customer.MODIFY;

MODIFYALL Function

MODIFYALL performs a bulk update of records.

MODIFYALL has the following syntax.

CopyCode image Copy Code
Record.MODIFYALL(Field, NewValue [, RunTrigger])

MODIFYALL uses the current filters, meaning that you can perform the update on a specified set of records within a table. MODIFYALL does not return any value, nor does it cause an error if the set of records to be changed is empty.

In the following example, the SETRANGE statement selects the records where Salesperson Code is PS. The MODIFYALL statement changes the Salesperson Code of these records to JR. The example requires that you create the following variable.

Variable | Data type | Subtype
Customer | Record | Customer
CopyCode image Copy Code
Customer.SETRANGE("Salesperson Code",'PS','PS');
Customer.MODIFYALL("Salesperson Code",'JR');

DELETE Function

DELETE deletes a record from the database.

DELETE has the following syntax.

CopyCode image Copy Code
[Ok :=] Record.DELETE([RunTrigger])

The record that you want to delete must be specified by using the values in the primary key fields before you call this function. This means that DELETE does take filters into consideration.

The following example shows how to use DELETE to delete the record for customer number 4711. This example requires that you create the following variable.

Variable | Data type | Subtype
Customer | Record | Customer
CopyCode image Copy Code
Customer."No." := '4711';
Customer.DELETE;

DELETE returns an optional Boolean value. It returns TRUE if the record could be found; otherwise, it returns FALSE. Unless you test this value in your code, a run-time error occurs when DELETE fails

When you are developing your own applications, you should consider the following scenario:

  1. Retrieve a record from the database.

  2. Perform various checks to determine whether the record should be deleted.

  3. If step 2 indicated that you should delete the record, then delete it.

This can cause problems in a multi-user environment. Another user can modify or delete the same record between your performing steps 2 and 3. If the record is modified, then perhaps the new contents of the record would have changed your decision to delete it. If it has been deleted by the other user, you can get a run-time error if you have just verified that the record existed (in step 1). If the design of your application indicates that you can encounter this problem, you should consider using the LOCKTABLE function. LOCKTABLE should be used sparingly because this function degrades performance. For more information about the LOCKTABLE function, see LOCKTABLE Function.

DELETEALL Function

DELETEALL deletes all the records that are specified by the filter settings. If no filters are applied, it deletes all the records in the table.

DELETEALL has the following syntax.

CopyCode image Copy Code
Record.DELETEALL([RunTrigger])

The following example deletes all the records from the Customer table where the Salesperson Code is PS. This example requires that you create the following variable.

Variable | Data type | Subtype
Customer | Record | Customer
CopyCode image Copy Code
Customer.SETRANGE("Salesperson Code", 'PS', 'PS');
Customer.DELETEALL;
Note Note

When you use DELETEALL(TRUE), C/SIDE creates a copy of the C/AL variable with its initial values. This means that when you use DELETEALL(TRUE) to run the OnDelete trigger, all the changes that were made to the variables in the function or codeunit that is making the call cannot be seen in the OnDelete trigger. If you want to see the changes made to the variables, you must use DELETE(TRUE) in a loop. There is no difference in performance between using DELETEALL(TRUE) and using DELETE(TRUE) in a loop.


LOCKTABLE Function

Ordinarily, when you are developing applications in C/SIDE, you do not need to take into consideration transactions and table locking. There are, however, some situations in which you must lock a table explicitly. To do this, use the LOCKTABLE function.

For example, in the beginning of a function, you inspect data in a table and then use this data to perform various checks and calculations. Finally, you want to insert a record based on the result of these calculations. To ensure that your calculations make sense, you must be certain that the values you retrieved at the beginning of the transaction are consistent with the data that is in the table now. You cannot allow other users to update the table while your function is performing its calculations.

LOCKTABLE Function

You can use the LOCKTABLE function to lock the table at the start of your function.

LOCKTABLE has the following syntax.

CopyCode image Copy Code
Record.LOCKTABLE([Wait] [, VersionCheck])

For more information about concurrency in Microsoft Dynamics NAV, see the following topics:

Read Consistency and Concurrency

Multiuser Environments


CALCFIELDS, CALCSUMS,FIELDERROR, FIELDNAME, INIT, TESTFIELD, and VALIDATE Functions

CALCFIELDS, CALCSUMS,FIELDERROR, FIELDNAME, INIT, TESTFIELD, and VALIDATE Functions

The following functions perform various actions on fields:

  • CALCFIELDS

  • CALCSUMS

  • FIELDERROR

  • FIELDNAME

  • INIT

  • TESTFIELD

  • VALIDATE

CALCFIELDS Function

CALCFIELDS updates FlowFields. FlowFields are automatically updated when they are the direct source expressions of controls, but they must be explicitly calculated when they are part of a more complicated expression. For more information about flowfields, see FlowFields Overview.

CALCFIELDS has the following syntax.

CopyCode image Copy Code
[Ok :=] Record.CALCFIELDS(Field1, [Field2],...)

When you use FlowFields in C/AL functions, you must use the CALCFIELDS function to update them.

In the following example, the SETRANGE function sets a filter and then the CALCFIELDS function calculates the Balance and Balance Due fields by using the current filter and performing the calculations that are defined as the CalcFormula properties of the FlowFields. This example requires that you create the following variable.

Variable | Data type | Subtype
Customer | Record | Customer
CopyCode image Copy Code
Customer.GET('01454545');
Customer.SETRANGE("Date Filter",0D,TODAY);
Customer.CALCFIELDS(Balance,"Balance Due");
MESSAGE('The Balance is %1 and your Balance Due is %2',Customer.Balance,Customer."Balance Due");

The following message is displayed:

The Balance is 342,529.44 and your Balance Due is 342,529.44

CALCSUMS Function

CALCSUMS calculates the sum of one or more fields that are SumIndexFields in the record.

CALCSUMS has the following syntax.

CopyCode image Copy Code
[Ok :=] Record.CALCSUMS (Field1, [Field2],...)

For CALCSUMS, a key that contains the SumIndexFields must be selected as the current key. Similar to CALCFIELDS, CALCSUMS uses the current filter settings when performing the calculation.

In the following example, an appropriate key is selected, some filters are set, the calculation is performed and then a message is displayed. This example requires that you create the following variable.

Variable | Data type | Subtype
custledgerentry | Record | Cust. Ledger Entry
CopyCode image Copy Code
custledgerentry.SETCURRENTKEY("Customer No.");
custledgerentry.SETRANGE("Customer No.",'10000','50000');
custledgerentry.SETRANGE("Posting Date",0D,TODAY);
custledgerentry.CALCSUMS("Sales (LCY)");
MESSAGE ('%1 calculated sales',custledgerentry."Sales (LCY)")

FIELDERROR Function

FIELDERROR triggers a run-time error after displaying a field-related error message.

FIELDERROR has the following syntax.

CopyCode image Copy Code
Record.FIELDERROR(Field, [Text])

This function is very similar to the ERROR function. However, in the FIELDERROR function, if the name of a field is changed, for example, translated to another language, in the Table Designer, the message from the FIELDERROR function will reflect the current name of the field.

The following examples show how to use the FIELDERROR function. These examples require that you create the following variable.

Variable | Date type | Subtype
Item | Record | Item
CopyCode image Copy Code
Item.GET('70000');
IF Item.Class <> 'HARDWARE' THEN
   Item.FIELDERROR(Class);

If item 70000 has a Class other than HARDWARE, then the following error message is displayed:

Class must not be OTHER in Item No. ='70000'.

If the text or code field contains the empty string, then the following error message is displayed:

You must specify Class in Item No.='70000'.

If the field is a numeric field and is empty, it is treated as though it contains the value 0 (zero) and the following error message is displayed:

Class must not be 0 in Item No.='70000'.

You can change the default text that is displayed in the error message. The following example shows how to use the FIELDERROR function and change the default text. This example requires that you create the following variable.

Variable | Data type
Class | Code
CopyCode image Copy Code
IF Item.Class < '4711' THEN
   Item.FIELDERROR(Class,'must be greater than 4711');

The following error message is displayed:

Class must be greater than 4711 in Item No.='70000'.

FIELDNAME

FIELDNAME returns the name of a field. It has the following syntax.

CopyCode image Copy Code
Name := Record.FIELDNAME(Field)

You could simply use the name of the field. However, using FIELDNAME allows you to create messages that always contain the name of the field, even if the name of the field is changed.

This example shows how to use FIELDNAME together with FIELDERROR.

CopyCode image Copy Code
FIELDERROR(
   Quantity,'must not be less than ' + FIELDNAME("Quantity Shipped"));

INIT

INIT initializes a record. It has the following syntax.

CopyCode image Copy Code
Name := Record.FIELDNAME(Field)

If a default value for a field has been defined with the InitValue property, this value is used for the initialization. Otherwise, the default value of each data type is used

Note Note

INIT does not initialize the fields of the primary key.

TESTFIELD Function

TESTFIELD tests whether a field contains a specific value. It has the following syntax.

CopyCode image Copy Code
Record.TESTFIELD(Field, [Value])

If the test fails, that is, if the field does not contain the specified value, an error message is displayed and a run-time error is triggered. This means that any changes that were made to the record are discarded. If the value that you test against is an empty string, the field must have a value other than blank or 0 (zero).

The following example tests the Language Code field for customer number 10000 in the Customer table and tests whether the Language Code is ZX. This example requires that you create the following variable.

Variable | Data type | Subtype
customer | Record | Customer
CopyCode image Copy Code
customer.GET('10000')
customer.TESTFIELD("Language Code",'ZX');

VALIDATE Function

VALIDATE calls the OnValidate trigger of a field. It has the following syntax.

CopyCode image Copy Code
Record.VALIDATE(Field [, NewValue])

When you enter an account number in a ledger, code in a table trigger is executed to transfer the name of the account from the chart of accounts. If you enter an account number in a batch job, the code which transfers the name of the account is not automatically executed. The following example executes the appropriate field-level trigger code. This example requires that you create the following variable.

Variable | Data type | Subtype
GeneralLedgerEntry | Record | G/L Entry
CopyCode image Copy Code
GeneralLedgerEntry.VALIDATE("G/L AccountNo", '100');

This corresponds to the following code.

CopyCode image Copy Code
GeneralLedgerEntry."G/L AccountNo" := '100';
GeneralLedgerEntry.VALIDATE("G/L AccountNo");

The VALIDATE function is useful for centralizing processing, which makes your application easier to maintain.

For example, if the OnValidate trigger of the Total Amount field performs a calculation that uses values from three other fields as operands, the calculation must be performed again if the contents of any of these fields changes. You should avoid entering the calculation formula in the OnValidate triggers of each field because this can create errors if the calculation formula has to be changed later and you have to update the code in all the triggers. Instead, you should enter the calculation formula in the OnValidate trigger of only one of the fields and call this trigger code from the OnValidate triggers of the other fields.


Progress Windows, MESSAGE, ERROR and CONFIRM Functions

Progress Windows, MESSAGE, ERROR and CONFIRM Functions

You can use several specialized functions to display messages and gather input. We recommend that you use forms and pages to ensure that your application has a consistent user interface. However, there are situations where you may need to use the dialog functions instead of forms. The most important uses of the dialog functions are the following:

  • To display a window that indicates the progress of some processing that may take a long time.

  • To stop the running program to display an error message.

  • To allow the user to confirm a choice before the program continues running.

You can also use the STRMENU function to create forms that present options to the user. It is much faster to use this function than to design a form which only presents a limited set of options to the user. For more information about the STRMENU function, see STRMENU Function.

Best Practices for User Messages

We recommend the following guidelines for writing messages for end users:

  • Write messages correctly according to the grammatical rules for your language.

  • When you write a message that is similar to one in the .etx file, phrase it to be as similar to the .etx message as possible. This will make messages consistent throughout the system.

  • Do not use backslashes to indicate line breaks in a message. Line formatting is done automatically. The only exception is in the OPEN Function (Dialog). You must use backslashes for the message to be aligned correctly.

  • Use the FIELDCAPTION Function (Record) and TABLECAPTION Function (Record) whenever possible to return names of fields and tables as strings so that the user can always recognize a term that indicates a field or table name. The only exception to this is in OPEN Function (Dialog). In this function, you can use the field name directly. Otherwise, it can be difficult to align correctly. If you refer to a field name without using the FIELDCAPTION function, then type the field name without any single or double quotation marks.

  • Try to write all messages on only one line. If you need to use more than one line, then start each new line after a period rather than in the middle of a sentence.

  • Do not enter the text directly in the C/AL code. Instead, enter it as a text constant so that the message can be translated.

Creating a Window to Indicate Progress

If you have an application that performs some processing that can take a long time to complete, then you should consider displaying a window that informs the user of the progress that is being made. It is always a good idea to inform the user that processes are still running.

A Cancel button is automatically added to every dialog window and gives the user the opportunity to stop the processing.

In some applications, you may want to create an indicator control to show progress. For more information, see How to: Use an Indicator to Display Values. In other applications, you may want to create a window in which each field is updated while the program is running. For example, the fields in the window display the count of the number of postings made. In another application, you may want to display information about the record that is currently being processed. For example, the field in the window displays the number of the account that is currently being processed.

To create this type of progress window, you use the Dialog data type. For more information, see How to: Create a Progress Window.

MESSAGE Function

The MESSAGE Function (Dialog) displays a message in a window that remains open until the user clicks OK on the window.

The MESSAGE function has the following syntax.

CopyCode image Copy Code
MESSAGE(String [, Value1, ...])

The MESSAGE function executes asynchronously, which means that MESSAGE is not executed until the function from which it was called ends or another function requests user input. The function is useful for notifying the user that some processing has been successfully completed.

For an example of the MESSAGE function, see codeunit 83 in the standard application. The code in the OnRun trigger converts a Quote into a Sales Order and then displays a message. The message is generated by the following code.

CopyCode image Copy Code
MESSAGE(Text001,"No.",SalesHeader2."No.");

Text001 is a text constant that contains the following text:

Quote %1 has been changed to order %2.

Note Note

Unlike the progress window, the MESSAGE function does not require that you first declare a variable of type Dialog. The MESSAGE function creates a window of its own.

ERROR Function

The ERROR Function (Dialog) is very similar to the MESSAGE function except that when the user has acknowledged the message from an ERROR function, execution ends. The ERROR function is also similar to the FIELDERROR function. For more information, see CALCFIELDS, CALCSUMS,FIELDERROR, FIELDNAME, INIT, TESTFIELD, and VALIDATE Functions.

The ERROR function has the following syntax.

CopyCode image Copy Code
ERROR(String [, Value1, ...])

CONFIRM Function

The CONFIRM Function (Dialog) is used in the same way as the MESSAGE function to display a message. However, unlike the MESSAGE function, the CONFIRM function has a required return value.

The CONFIRM function has the following syntax.

CopyCode image Copy Code
Ok := Dialog.CONFIRM(String [, Default] [, Value1] ,...)

The following example shows how to use the CONFIRM function.

CopyCode image Copy Code
IF CONFIRM('Do you want to post the journal lines and print the report(s)?',FALSE) THEN
   MESSAGE('Posting')
ELSE
   MESSAGE('No Posting');
   EXIT;

The FALSE parameter in the CONFIRM statement means that No is the default.


How to: Create a Progress Window

How to: Create a Progress Window

If you have an application that performs some processing which can take a long time to complete, you should consider displaying a window that informs the user of the progress that is being made.

You can create a window in which each field is updated while the program is running. For example, the fields in a window display the count of the number of postings made. You can also display information about the record that is currently being processed. For example, the field in a window displays the number of the account that is currently being processed.

To create a progress window

  1. Click the Tools menu and then click Object Designer.

  2. In Object Designer, select Codeunit, and then click New.

  3. Click the View menu, and then click C/AL Globals.

  4. On the Variables tab, in the Name field, enter ProgressWindow. In the Data Type field, select Dialog from the drop-down list.

  5. On the Variables tab, on a new line in the Name field, enter ChartOfAcc. In the Data Type field, select Record from the drop-down list. In the Subtype field, select G/L Account from the table list.

  6. In the C/AL Editor for the dialog, add the following code.

    CopyCode image Copy Code
    ProgressWindow.OPEN('Processing account number #1#######');
REPEAT
   SLEEP(1000);
   ProgressWindow.UPDATE(1,ChartOfAcc."No.");
   // Process the account.
UNTIL ChartOfAcc.NEXT = 0;
ProgressWindow.CLOSE;

    The first line defines the string that will be displayed in the progress window. The part of the string that contains the number signs (#) and a number defines the field that will be displayed in the window. The number (1) refers to the field.

    In this example, each entry in the G/L Account table is updated and the number of each account is displayed as it is updated.

    The SLEEP(1000); function is necessary only to slow the processing so that you can see the progress window.

See Also

Tasks

How to: Use an Indicator to Display Values

Concepts

Progress Windows, MESSAGE, ERROR and CONFIRM Functions


STRMENU Function

STRMENU Function

STRMENU creates and displays a form with an option group and returns the selection that the user makes.

STRMENU has the following syntax.

CopyCode image Copy Code
OptionNumber := Dialog.STRMENU(OptionString [, DefaultNumber]);

OptionNumber is the number of the option that the user chooses. The first option in OptionString is number 1. If the user closes the form with ESC, STRMENU returns 0 (zero). If it is defined, DefaultNumber is used to select the default option. If DefaultNumber is not defined, option number 1 is used as the default.

Example

The following example creates a window with the following options:

  • Save

  • Close

  • Cancel

The window also has an OK button and a Cancel button.

This example requires that you create the following variable.

Variable | Data type
Selection | Integer
CopyCode image Copy Code
Selection := Dialog.STRMENU('Save,Close,Cancel',3);

In this example, the Cancel option is the default because the DefaultNumber parameter was set to 3. We recommend that you set the default to a harmless action, such as cancel, because this option can be selected by pressing ENTER. If the user inadvertently presses ENTER, nothing catastrophic happens, as might be the case if the default option was "Delete all."

See Also

Concepts

Progress Windows, MESSAGE, ERROR and CONFIRM Functions


C/AL Reserved Words

C/AL Reserved Words

C/AL has several reserved words that you cannot use as variable, constant, or function names in your application. Reserved words include the following types:

  • Data types

  • Keywords

  • Functions

  • Operators

  • Properties

  • System variable names

  • Triggers

In some cases, you can use reserved words as variable names if you enclose the variable name in quotation marks. However, we do not recommend this practice.

If you write code on client report definition (RDLC) report layouts, then verify that your code does not use Visual Studio Report Designer reserved words. For more information, see Using Expressions in a Report (Visual Studio Report Designer) and its subtopics.

List of reserved words

The following table lists all of the C/AL reserved words.

Reserved word | Type
Abs | Function
Activate | Function
Active | Function
ActiveControlOnOpen | Property
Addlink | Function
Addtext | Function
AltSearchField | Property
And | Operator
Applicationpath | Function
Array | Functions
ArrayLen | Function
Ascending | Function
AssertError | Keyword
AssistEdit | Property
AutoCalcField | Property
AutoEnter | Property
AutoFormatExpr | Property
AutoFormatType | Property
AutoIncrement | Property
Automation | Data type
AutoPosition | Property
AutoRepeat | Property
AutoReplace | Property
AutoSave | Property
AutoSplitKey | Property
AutoUpdate | Property
BackColor | Property
BackTransparent | Property
BackupKey | Property
Beep | Function
Begin | Keyword
BigInteger | Data type
BigText | Data type
Binary | Data type
Bitmap | Property
BitmapList | Property
BitmapPos | Property
BlankNumbers | Property
BlankZero | Property
BLOB | Data type
Boolean | Data type
Border | Property
BorderColor | Property
BorderStyle | Property
BorderWidth | Property
BottomMargin | Property
Break | Function
CalcDate | Function
CalcField | Function
CalcFields | Function, Property
CalcFormula | Property
CalcSum | Function
CalcSums | Function
CallFieldValidate | Property
Cancel | Property
Caption | Function, Property
CaptionBar | Property
CaptionClass | Property
CaptionML | Property
CardFormID | Property
Case | Keyword
ChangeCompany | Function
Char | Data type
CharAllowed | Property
ChartPartID | Property
CheckLicenseFile | Function
Class | Function
Clear | Function
ClearAll | Function
ClearLastError | Function
ClearMarks | Function
ClearOnLookup | Property
Close | Function
ClosingDate | Function
ClosingDates | Property
Clustered | Property
Code | Data type
CodeCoverageLog | Function
Codeunit | Data type
CommandLine | Function
Commit | Function
CompanyName | Function
CompressArray | Function
Compressed | Property
Confirm | Function
Consistent | Function
ContainerType | Property
ContextURL | Function
ControlAddin | Property
ControlType | Property
ConvertStr | Function
Copy | Function
CopyArray | Function
CopyFilter | Function
CopyFilters | Function
CopyLinks | Function
CopyStr | Function
CopyStream | Function
Count | Function
CountApprox | Function
Create | Function
CreateDateTime | Function
CreateGUID | Function
CreateInstream | Function
CreateOutstream | Function
CreateTempFile | Function
CreateTotals | Function
CurrentDateTime | Function
CurrentKey | Function
CurrentKeyIndex | Function
CurrentTransactionType | Function
CurrFieldNo | System Variable
CurrForm | System Variable
CurrReport | System Variable
DataCaptionExpr | Property
DataCaptionFields | Property
DataItemIndent | Property
DataItemLink | Property
DataItemLinkReference | Property
DataItemSeparator | Property
DataItemTable | Property
DataItemTableView | Property
DataItemVarName | Property
DataLength | Property
DataPerCompany | Property
Dataport | Data type
Date | Data type
Date2DMY | Function
Date2DWY | Function
DateFormula | Data type, Property
DateTime | Data type
DaTi2Variant | Function
Decimal | Data type
DecimalPlaces | Property
DecimalPlacesMax | Function
DecimalPlacesMin | Function
Default | Property
DefaultFieldsValidation | Property
DelayedInsert | Property
DelChr | Function
Delete | Function
DeleteAll | Function
DeleteAllowed | Property
DeleteLink | Function
DeleteLinks | Function
DelStr | Function
Description | Property
DeviceFontName | Property
Dialog | Data type
Dimensions | Property
Direction | Property
Div | Operator
Divisor | Property
DMY2Date | Function
Do | Keyword
Download | Function
DownloadFromStream | Function
DownTo | Keyword
DrillDown | Property
DrillDownFormID | Property
DropDown | Property
DT2Date | Function
DT2Time | Function
Duplicate | Function
Duration | Data type
DWY2Date | Function
Editable | Function, Property
Ellipsis | Property
Else | Keyword
Enabled | Function, Property
EnabledIfError | Property
EnabledIfInsertion | Property
EnabledIfSelection | Property
Encoding | Property
End | Keyword
Environ | Function
EOS | Function
Erase | Function
Error | Function
Evaluate | Function
Exists | Function
Exit | Keyword
Export | Function
ExportObjects | Function
ExtendedDataType | Property
Field | Function
Field No. | Property
FieldActive | Function
FieldCaption | Function
FieldClass | Property
FieldCount | Function
FieldEndDelimiter | Property
FieldError | Function
FieldExist | Function
FieldIndex | Function
FieldName | Function
FieldNo | Function
FieldRef | Data type
FieldSeparator | Property
FieldStartDelimiter | Property
FieldValidate | Property
File | Data type
FileFormat | Property
FileName | Function, Property
FilterGroup | Function
Find | Function
FindFirst | Function
FindLast | Function
FindSet | Function
Focusable | Property
FocusOnClick | Property
FontBold | Property
FontItalic | Property
FontName | Property
FontSize | Property
FontStrikethru | Property
FontUnderline | Property
For | Keyword
ForeColor | Property
Form | Data type
Format | Function, Property
FreezeColumnID | Property
FunctionType | Property
Get | Function
GetFilter | Function
GetFilters | Function
GetLastErrorText | Function
GetPosition | Function
GetRangeMax | Function
GetRangeMin | Function
GetRecord | Function
GetStamp | Function
GetSubtext | Function
GetTable | Function
GetView | Function
GlobalLanguage | Function
GroupTotalFields | Property
GroupType | Property
GUIAllowed | Function
GUID | Data type
HandlerFunctions | Property
HasFilter | Function
HasLinks | Function
HasValue | Function
HeadingHeight | Property
Height | Function, Property
HideValue | Property
HorzAlign | Property
HorzGlue | Property
HorzGrid | Property
Hyperlink | Function
ID | Property
If | Keyword
Image | Property
Import | Function, Property
Importance | Property
ImportObjects | Function
In | Operator
IncludeInDataSet | Property
InColumn | Property
InColumnHeading | Property
IncStr | Function
Indent | Property
Indentation | Property
IndentationColumnName | Property
IndentationControls | Property
InFooterBar | Property
InFrame | Property
Init | Function
InitValue | Property
InlineEditing | Function, Property
InMatrix | Property
InMatrixHeading | Property
InPage | Property
Input | Function
Insert | Function
InsertAllowed | Property
InsStr | Function
InStream | Data type
InstructionalTextML | Property
Integer | Data type
InvalidActionAppearance | Property
IsAction | Function
IsAutomation | Function
IsBinary | Function
IsBoolean | Function
IsChar | Function
IsClear | Function
IsCode | Function
IsCodeunit | Function
IsDate | Function
IsDateFormula | Function
IsDecimal | Function
IsEmpty | Function
IsFile | Function
IsInstream | Function
IsInteger | Function
IsNullGUID | Function
IsOption | Function
IsOutstream | Function
IsRecord | Function
IsText | Function
IsTime | Function
IsTransactionType | Function
KeepWithNext | Property
Key | Property
KeyCount | Function
KeyGroupDisable | Function
KeyGroupEnable | Function
KeyGroupEnabled | Function
KeyGroups | Property
KeyIndex | Function
KeyRef | Data type
Language | Function
LeaderDots | Property
LeftMargin | Property
Len | Function
Length | Function
LinkedInTransaction | Property
LinkedObject | Property
LinkFields | Property
LinksAllowed | Property
LinkTable | Property
LinkTableForceInsert | Property
LockTable | Function
LockTimeout | Function
LogHeight | Function, Property
LogWidth | Function, Property
Lookup | Property
LookupFormID | Property
LookupMode | Function, Property
Lowercase | Function
MaintainSIFTIndex | Property
MaintainSQLIndex | Property
Mark | Function
MarkedOnly | Function
MatrixColumnWidth | Property
MatrixSourceTable | Property
Maximizable | Property
MaximizedOnOpen | Function, Property
MaxIteration | Property
MaxLength | Property
MaxOccurs | Property
MaxStrLen | Function
MaxValue | Property
MenuItemType | Property
MenuLevel | Property
Message | Function
Minimizable | Property
MinimizedOnOpen | Function, Property
MinOccurs | Property
MinValue | Property
Mod | Operator
Modify | Function
ModifyAll | Function
ModifyAllowed | Property
MultiLine | Property
MultipleNewLines | Property
Name | Function, Property
NewPage | Function
NewPagePerGroup | Property
NewPagePerRecord | Function, Property
Next | Function
NextControl | Property
NodeName | Property
NodeType | Property
NormalDate | Function
Not | Operator
NotBlank | Property
Number | Function
Numeric | Property
ObjectID | Function
Occurrence | Property
OCX | Data type
Of | Keyword
OnAction | Trigger
OnActivate | Trigger
OnActivateForm | Trigger
OnAfterAssignField | Trigger
OnAfterAssignVariable | Trigger
OnAfterExportRecord | Trigger
OnAfterFormatField | Trigger
OnAfterGetField | Trigger
OnAfterGetRecord | Trigger
OnAfterImportRecord | Trigger
OnAfterInitRecord | Trigger
OnAfterInput | Trigger
OnAfterInsertRecord | Trigger
OnAfterTestRun | Trigger
OnAfterValidate | Trigger
OnAssistEdit | Trigger
OnBeforeEvaluateField | Trigger
OnBeforeExportRecord | Trigger
OnBeforeImportRecord | Trigger
OnBeforeInput | Trigger
OnBeforeInsertRecord | Trigger
OnBeforePassField | Trigger
OnBeforePassVariable | Trigger
OnBeforePutRecord | Trigger
OnBeforeTestRun | Trigger
OnCloseForm | Trigger
OnControlAddin | Trigger
OnCreateHyperlink | Trigger
OnDeactivate | Trigger
OnDeactivateForm | Trigger
OnDelete | Trigger
OnDeleteRecord | Trigger
OnDrillDown | Trigger
OnFindRecord | Trigger
OnFormat | Trigger
OnHyperlink | Trigger
OnInit | Trigger
OnInitDataPort | Trigger
OnInitReport | Trigger
OnInitXMLport | Trigger
OnInputChange | Trigger
OnInsert | Trigger
OnInsertRecord | Trigger
OnLookup | Trigger
OnModify | Trigger
OnModifyRecord | Trigger
OnNewRecord | Trigger
OnNextRecord | Trigger
OnOpenForm | Trigger
OnPostDataItem | Trigger
OnPostDataport | Trigger
OnPostReport | Trigger
OnPostSection | Trigger
OnPostXMLport | Trigger
OnPreDataItem | Trigger
OnPreDataport | Trigger
OnPreReport | Trigger
OnPreSection | Trigger
OnPreXMLItem | Trigger
OnPreXMLport | Trigger
OnPush | Trigger
OnQueryCloseForm | Trigger
OnQueryClosePage | Trigger
OnRename | Trigger
OnTimer | Trigger
OnValidate | Trigger
Open | Function
Option | Data type
OptionCaption | Function, Property
OptionCaptionML | Property
OptionString | Function, Property
OptionValue | Property
Or | Operator
Orientation | Property
OSVersion | Function
OutStream | Data type
PadChar | Property
PadStr | Function
Page | Data type
PageNames | Property
PageNamesML | Property
PageNo | Function
PagePartID | Property
PageType | Property
PaperSize | Property
PaperSource | Function
PaperSourceFirstPage | Property
PaperSourceOtherPages | Property
ParentControl | Property
PartType | Property
PasswordText | Property
PasteIsValid | Property
Percentage | Property
PermanentAssist | Property
Permissions | Property
PlaceInBottom | Property
PopulateAllFields | Property
Pos | Function
Power | Function
Preview | Function
PrintOnEveryPage | Property
PrintOnlyIfDetail | Function, Property
ProcessingOnly | Property
Promoted | Property
PromotedCategory | Property
PromotedIsBig | Property
ProviderID | Property
PushAction | Property
QueryReplace | Function
Quit | Function
Random | Function
Randomize | Function
Read | Function
ReadConsistency | Function
ReadPermission | Function
ReadText | Function
Rec | System Variable
Record | Data type
RecordID | Data type
RecordLevelLocking | Function
RecordRef | Data type
RecordSeparator | Property
Relation | Function
Rename | Function
Repeat | Keyword
Report | Data type
ReqFilterFields | Property
ReqFilterHeading | Property
ReqFilterHeadingML | Property
RequestOptionsForm | System Variable
Reset | Function
RightMargin | Property
Round | Function
RoundDateTime | Function
RowHeight | Property
Run | Function
RunCommand | Property
RunFormLink | Property
RunFormLinkType | Property
RunFormOnRec | Property
RunFormView | Property
RunModal | Function
RunObject | Property
SaveAsExcel | Function
SaveAsHTML | Function
SaveAsPDF | Function
SaveAsXML | Function
SaveColumnWidths | Property
SaveControlInfo | Property
SavePosAndSize | Property
SaveRecord | Function
SaveTableView | Property
SaveValues | Property
SectionHeight | Property
SectionWidth | Property
Seek | Function
SelectLatestVersion | Function
SelectStr | Function
SerialNumber | Function
SetCurrentKey | Function
SetFilter | Function
SetPermissionFilter | Function
SetPosition | Function
SetRange | Function
SetRecFilter | Function
SetRecord | Function
SetSelectionFilter | Function
SetStamp | Function
SetTable | Function
SetTableView | Function
SetView | Function
ShapeStyle | Property
Shell | Function
ShortCutKey | Property
ShowAsTree | Property
ShowCaption | Property
ShowOutput | Function
ShowPrintStatus | Property
ShowStatus | Property
SID | Function
SignDisplacement | Property
SingleInstance | Property
Sizable | Property
Skip | Function
Sleep | Function
SourceExpr | Property
SourceField | Property
SourceTable | Property
SourceTablePlacement | Property
SourceTableRecord | Property
SourceTableTemporary | Property
SourceTableView | Property
SourceType | Property
SQL Data Type | Property
SQLIndex | Property
StartPos | Property
StrCheckSum | Function
StrLen | Function
StrMenu | Function
StrPos | Function
StrSubstNo | Function
Style | Property
StyleExpr | Property
SubFormID | Property
SubFormLink | Property
SubFormView | Property
SubType | Property
SumIndexFields | Property
SynchronizeAllLogins | Function
SynchronizeSingleLogin | Function
System | Data type
SystemPartID | Property
TableBoxID | Property
TableCaption | Function
TableFilter | Data type
TableIDExpr | Property
TableName | Function
TableNo | Function, Property
TableRelation | Property
Temporary | Property
TemporaryPath | Function
TestField | Function
TestTableRelation | Property
Text | Data type
TextMode | Function
TextPos | Function
TextType | Property
Then | Keyword
Time | Data type
TimerInterval | Property
Title | Property
To | Keyword
Today | Function
ToolTip | Property
ToolTipML | Property
TopLineOnly | Property
TopMargin | Property
TotalFields | Property
TotalsCausedBy | Function
TransactionType | Data type, Property
TransferFields | Function
Trunc | Function
Type | Function
Until | Keyword
Update | Function
UpdateControls | Function
UpdateEditable | Function
UpdateFontBold | Function
UpdateForeColor | Function
UpdateIndent | Function
UpdateOnAction | Property
UpdateOnActivate | Property
UpdateSelected | Function
Upload | Function
UploadIntoStream | Function
Uppercase | Function
URL | Function
UseReqForm | Property
UseRequestForm | Function
UserID | Function
UseSystemPrinter | Property
Validate | Function
ValidateTableRelation | Property
Value | Function
ValuesAllowed | Property
VariableActive | Function
VariableName | Property
Variant | Data type
Variant2Date | Function
Variant2Time | Function
VertAlign | Property
VertGlue | Property
VertGrid | Property
Visible | Function, Property
While | Keyword
Width | Function, Property
WindowsLanguage | Function
With | Keyword
WithEvents | Property
WordDate | Function
Write | Function
WriteMode | Function
WritePermission | Function
WriteText | Function
XMLport | Data type
XMLVersionNo | Property
XOR | Operator
XPos | Function, Property
xRec | System variable
Yield | Function
YPos | Function, Property


Compiling Objects

Compiling Objects

Before you can run a Microsoft Dynamics NAV 2009 object, you must compile the object. To compile an object, in Object Designer, click Tools, and then click Compile. Any syntax errors are displayed in a dialog box. Any errors or warnings about obsolete constructs in a three-tier environment are displayed in the Error List window. The following types of obsolete construct errors and warnings are displayed:

  • Unsupported data type warnings for Binary and Dataport types

  • Unsupported function calls

Note Note

Unsupported function calls for reports are not reported in the Error List window.

If you select an error in the Error List window and then click Design, then the C/AL Editor opens for the object to which the error or warning relates.

Wrapping Obsolete Constructs

If you develop applications for both the Classic architecture and the RoleTailored architecture, then you may have some constructs in your code that are obsolete when run on the RoleTailored architecture but are valid when run on the Classic architecture. We recommend that you wrap these constructs in an IF statement that calls the ISSERVICETIER system function. The Error List window does not display obsolete constructs that are contained in an IF ISSERVICETIER conditional block of code.

See Also

Tasks

How to: Compile a Dataport
How to: Compile a MenuSuite Object
How to: Compile the Code in a Codeunit

Concepts

Developing Applications for the Classic Client and RoleTailored Client
Saving, Compiling, and Running Forms
Saving, Compiling, and Running Reports
Syntax Errors


Debugging C/AL Code

Debugging C/AL Code

The process of finding and correcting errors is called debugging. You debug objects that run in the Classic client with the Microsoft Dynamics NAV debugger. You debug objects that run in the RoleTailored client with Visual Studio.

In Microsoft Dynamics NAV 2009, code is executed in the common language runtime (CLR), which is the .NET Framework run-time environment. Microsoft Dynamics NAV 2009 has a Microsoft Dynamics NAV class library that contains .NET versions of C/AL functions. New objects in Microsoft Dynamics NAV 2009, such as pages and client report definition (RDLC) report layouts, were created with the Microsoft Dynamics NAV class library. These objects cannot run in the Classic client. This means that you cannot debug these objects with the Microsoft Dynamics NAV debugger. For objects that were available in previous versions of Microsoft Dynamics NAV and that are also available in the RoleTailored client, C# code was generated so that the objects run in the CLR. You can debug these objects in either the Microsoft Dynamics NAV debugger or in Visual Studio. You can debug objects that are available only in the Classic client, such as forms and dataports, in the Microsoft Dynamics NAV debugger but not in Visual Studio.

The following table shows the objects in Microsoft Dynamics NAV 2009 and which debugger to use.

Object Debugger

Table

Microsoft Dynamics NAV debugger or Visual Studio

Form

Microsoft Dynamics NAV debugger

Classic report layout

Microsoft Dynamics NAV debugger

RDLC report layout

Visual Studio

Dataport

Microsoft Dynamics NAV debugger

XMLport

Microsoft Dynamics NAV debugger or Visual Studio

Note Note

XMLports have new features in Microsoft Dynamics NAV 2009 that are only available with Microsoft Dynamics NAV Server. If you want to debug these features, then you must use Visual Studio.

Codeunit

Microsoft Dynamics NAV debugger or Visual Studio

MenuSuite

Not applicable. There is no code to debug on MenuSuite objects.

Page

Visual Studio

For more information about debugging objects in the Microsoft Dynamics NAV debugger, see Debugging with Microsoft Dynamics NAV Debugger.

For more information about debugging objects in Visual Studio, see Debugging With Visual Studio.

See Also

Concepts

Syntax Errors
Run-Time Errors
Program-Logic Errors
Using Zoom


Syntax Errors

Syntax Errors

Syntax errors are detected by the C/AL compiler when you try to compile C/AL code, either in a codeunit or as code in another object, such as a table, form, page, report, or dataport. The compiler will notify you of the error.

Correcting Syntax Errors

The compiler will notify you of a syntax error. When you press ENTER and acknowledge the error message, the C/AL editor will appear with the cursor in front of the offending expression.

A syntax error can be caused by a misspelling, a missing colon, or by code that uses undeclared variables. The compiler will not compile code that contains a syntax error, such as a missing THEN in an IF statement, or code that uses undeclared variables.

See Also

Concepts

Run-Time Errors
Program-Logic Errors


Run-Time Errors

Run-time errors occur when the program is executed. These errors are not detected by the compiler, because the code is syntactically correct.

Run-Time Errors

An example of a run-time error is a statement that causes division by zero. In the following statement, the syntax is correct, but the statement may cause a division by zero error if the variable Second_number is assigned a value of 0:

Ratio := First_number / Second_number;

The common trait of these errors is that the code works correctly in many situations, but fails in others. The risk is that since there is nothing syntactically wrong with the code, the error could occur when the program is already in use. Unless you handle the run-time error in your code, default messages will appear.

Run-Time Errors and Data Consistency

There may be instances when run-time errors can compromise the integrity of the database. For example, if some fields are updated in a trigger and a run-time error occurs while other fields have not been updated. When a trigger is entered, a write transaction begins. If a run-time error occurs inside the trigger, the write transaction is rolled back and the execution of the trigger is terminated.

How to Avoid Run-Time Errors

The following guidelines show how to avoid run-time errors. These are only guidelines, as the conditions under which run-time errors occur are dependent on the context of your application.

If, for example, you use the GET function to locate a record, you must be prepared handle the possibility that a run-time error can occur if there are situations where no record is found. If you are certain that the specific context precludes this situation, you can omit handling a possible run-time error. (The context could be that the existence of a record is verified before the GET function is used.)

There are two categories of run-time errors:

  • Errors that are related to the use of data types

  • Errors that occur if a function does not succeed in doing what it is supposed to do

Division by zero does not fit into either of these categories, but it has been placed in the first one.

You can only prevent some errors (mainly related to data types) from occurring. Other errors cannot always be avoided, but you can write code that shields the user from the error. Instead of the default error handling (which displays a message, closes the form that was active when the error occurred, and rolls back any changes to the database), you can write an error handler that, for example, gives the user an opportunity to correct the input that caused the error. This error will display a message that explains why the error occurred.

Data Type-Related Errors

The easiest way to avoid data type-related errors is to use the correct data types. Errors like the type conversion error in the previous example and overflow errors can be avoided by using the correct data types.

A division by zero error can be avoided in several ways, depending upon the context where the code fragment is used. If the user enters the denominator (the Second_number variable) in a text box immediately before the evaluation of the statement, you could test the value of Second_number before performing the division, and reject a value of 0 (zero):

IF Second_number <> 0 THEN

Ratio := First_number / Second_number

ELSE

MESSAGE('Second_number must not be 0');

If Second_number is a field in a database table, and it should never be allowed to have a value of 0 (zero), the best place to perform this check is in the OnValidate trigger of the field. This enables you to ensure that a value of 0 (zero) can never be entered in the field.

Other Run-time Errors

Any function that fails to accomplish what it is intended to do can cause a run-time error. A good example is the GET function, which is used to locate a record in a table according to criteria that you specify.

The syntax of the GET function is:

[Ok :=] Record.GET([Value1], [Value2 ],...)

The return value of the function is Ok, a Boolean. If a record is found, the return value is TRUE; otherwise, it is FALSE. This return value can be ignored, as indicated by the square brackets. If it is ignored and the requested record cannot be found, a run-time error occurs and a system-generated error message is displayed. However, if you test the return value and a run-time error does not occur, it is assumed that you handle the condition yourself.

The C/SIDE Reference Guide provides information about how other functions handle errors. You can also look at the syntax description in the Symbol Menu, to see if the function returns a value called Ok. If it does, consult the C/SIDE Reference Guide to see which functions return a Boolean for other reasons than those described here. For example, the ASCENDING function can be used to check the sort order of a table. In this case, it returns TRUE if the sort order is ascending, and FALSE if it is descending.

If you use the return value in either of the following examples, you can shield the user from a run-time error.

Example 1:

IF NOT Customer.GET("No.") THEN

Customer.INIT;

Example 2:

IF NOT Customer.GET("No.") THEN

BEGIN

MESSAGE('Customer %1 not found', "No.");

EXIT;

END;

In the first example, if a Customer record with the given number (No.) cannot be retrieved, an (empty) record is initialized. In the second example, the user is notified that the record cannot be found and the trigger from where the GET function was called is exited. These examples are only general guidelines. You must consider how to handle situations like these in the context of your own application.

Finding and Correcting Run-time Errors

To determine the cause of a run-time error, you need the exact description of the sequence of events that led to the error. The sequence of events should include the following:

  • What the user was doing at the time of the error

  • What values the user entered

  • What record caused the error

If the error was caused by a calculation that failed to check whether a division by zero was about to be carried out, you should be able to find the statement that led to the error. However, if the circumstances that led to the error are more complicated, and you cannot determine the exact location of the error, you can use the debugger.

See Also

Concepts

Syntax Errors
Program-Logic Errors


Program-Logic Errors

Program-Logic Errors

A program logic error is an error in an application that compiles and runs without causing run-time errors, but fails to function as intended.

Program Logic Errors

Because of their similarities, many, if not most, run-time errors are also program logic errors. However, the "real" program logic error will not make itself noticed in a similarly spectacular way but will generate incorrect data that may not always be detected. A way to avoid program logic errors is to test the functionality of a program and evaluate if the data the program generates is correct.

See Also

Concepts

Syntax Errors
Run-Time Errors


Debugging With Visual Studio

Debugging With Visual Studio

In Microsoft Dynamics NAV 2009, you can use Visual Studio to debug objects that run on the RoleTailored client. The topics in this section describe how to enable debugging for objects in the RoleTailored client and how to use Visual Studio to debug these objects.

Before you start debugging objects in the RoleTailored client, you must install Visual Studio 2005 SP1 or Visual Studio 2008 SP1 on the computer running Microsoft Dynamics NAV Server.

To debug objects that run on the Classic client, use the Microsoft Dynamics NAV debugger.

See Also

Tasks

How to: Enable Debugging
How to: Attach Visual Studio to the Microsoft Dynamics NAV Server Service
Walkthrough: Debugging an Action on a Page

Concepts

Debugging with Microsoft Dynamics NAV Debugger


How to: Enable Debugging

How to: Enable Debugging

You use Visual Studio to debug objects that run in the RoleTailored client.

Before you start debugging with Visual Studio, you must enable Microsoft Dynamics NAV 2009 for debugging and then attach Visual Studio to the Microsoft Dynamics NAV Server service. This procedure describes how to enable Microsoft Dynamics NAV 2009 for debugging.

To enable Microsoft Dynamics NAV 2009 for debugging

  1. On the computer running Microsoft Dynamics NAV Server, open the CustomSettings.config file. This file is typically located at %programfiles%\Microsoft Dynamics NAV\60\service.

  2. Change the value of the EnableDebugging key to true:

    CopyCode image Copy Code
    <add key="EnableDebugging" value="true" />

  3. Save and close the CustomSettings.config file.

  4. In Control Panel, click Administrative Tools, and then click Services to open the Services snap-in.

  5. In the list of services, right-click Microsoft Dynamics NAV Server, and then click Restart.

  6. Start the RoleTailored client.

    Note Note

    When you start the RoleTailored client with debugging enabled, C# files are generated for every RoleTailored client object. Therefore, it takes longer to start the RoleTailored client. We recommend that you set the value of the EnableDebugging key to false after you finish debugging.

See Also

Tasks

How to: Attach Visual Studio to the Microsoft Dynamics NAV Server Service

Concepts

Debugging With Visual Studio


How to: Attach Visual Studio to the Microsoft Dynamics NAV Server Service

How to: Attach Visual Studio to the Microsoft Dynamics NAV Server Service
See Also

You use Visual Studio to debug objects that run in the RoleTailored client.

This procedure describes how to attach Visual Studio to the Microsoft Dynamics NAV Server service before you start debugging.

Before you start this procedure, you must do the following:

  • Enable Microsoft Dynamics NAV 2009 for debugging. For more information, see How to: Enable Debugging. After you enable Microsoft Dynamics NAV 2009 for debugging and then start the RoleTailored client, the C# files for RoleTailored client objects are created.

  • Install Visual Studio 2005 SP1 or Visual Studio 2008 SP1 on the computer running Microsoft Dynamics NAV Server.

To attach Visual Studio to the service

  1. Start Visual Studio.

    Note Note

    On a computer running Windows Vista with User Access Control enabled, you must start Visual Studio with administrator privileges. To do this, click Start, right-click Microsoft Visual Studio, and then click Run as administrator.

  2. In Visual Studio, open the C# file for the object that you want to debug. By default, when you enable Microsoft Dynamics NAV 2009 for debugging and then start the RoleTailored client, the C# files are created in the following folder: %systemdrive%\ProgramData\Microsoft\Microsoft Dynamics NAV\60\Server\MicrosoftDynamicsNavServer\source\<object>\

  3. On the Debug menu, click Attach to Process.

  4. In the Attach to Process window, select the Show processes from all users check box and the Show processes in all sessions check box.

  5. Under Available processes, select Microsoft.Dynamics.Nav.Server.exe from the Available Processes list.

  6. Above the Available Processes list, next to Attach to, click Select.

  7. In the Select Code Type window, select Debug these code types, select Managed from the list of code types, and then click OK.

    Note Note

    Debugging T-SQL code types is not supported. If you attach the debugger to T-SQL code while the RoleTailored client is running, then the client does not respond. If you attach the debugger to T-SQL code and then start the RoleTailored client, then you get an error that is similar to the following:

    The following SQL Server error or errors occurred:

    2812,"42000",[Microsoft][ODBC SQL Server Driver][SQL Server]Could not find stored procedure 'sp_sdidebug'.

    5703,"01000",[Microsoft][ODBC SQL Server Driver][SQL Server]Changed language setting to us_english.

    0,"01000",[Microsoft][ODBC SQL Server Driver]SQL Debugging disabled

    5701,"01000",[Microsoft][ODBC SQL Server Driver][SQL Server]Changed database context to 'master'.

  8. In the Attach to Process window, click Attach.

  9. Start using the RoleTailored client. When you hit a breakpoint, you can begin debugging in Visual Studio. For more information, see Debugging in Visual Studio.

See Also

Concepts

Debugging With Visual Studio


Walkthrough: Debugging an Action on a Page

Walkthrough: Debugging an Action on a Page

The following walkthrough demonstrates debugging an action on a page with Visual Studio. If you customize or create new objects for the RoleTailored client, then consider debugging those objects. You use Visual Studio to debug objects that run in the RoleTailored client. For more information, see Debugging in Visual Studio.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating a codeunit and creating an action on a page that runs that codeunit.

  • Enabling Microsoft Dynamics NAV 2009 for debugging.

  • Viewing the C# files that are created for Microsoft Dynamics NAV objects in Visual Studio.

  • Attaching Visual Studio to the Microsoft Dynamics NAV Server service.

  • Adding a breakpoint to a codeunit and running the action on the page with the breakpoint set.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009.

  • The CRONUS International Ltd. demo data company.

  • Visual Studio 2008 SP1 or Visual Studio 2005 SP1 on the computer running Microsoft Dynamics NAV Server.

Expand image Creating the Action on a Page

You will first create a codeunit. Then you will create an action on a page. The OnRun trigger of this action calls the codeunit.

To create the codeunit

  1. In Object Designer, click Codeunit, and then click New.

  2. On the View menu, click C/AL Globals.

  3. On the Variables tab, on a new line in the Name field, enter OK. In the Data Type field, select Boolean.

  4. On the Variables tab, on a new line in the Name field, enter MyCustomer. In the Data Type field, select Record. In the Subtype field, select Customer from the Table List. Close the C/AL Globals window.

  5. In the OnRun trigger of the codeunit, add the following code.

    CopyCode image Copy Code
    OK := MyCustomer.FINDFIRST;
MESSAGE('Debug test');

  6. On the File menu, click Save to save the new codeunit.

  7. In the Save As window, in the ID field, enter 50001. In the Name field, enter Debug Test. Select Compiled, and then click OK.

To create an action that runs a codeunit

  1. Create an action on page 22, Customer List. For more information, see How to: Add Actions to a Page. This action has the following characteristics:

    • The caption is Debug Test.

    • The type is Action.

    • It does not have a SubType.

    • It is under the Action group that has the caption Customer.

  2. Select Action Designer. On the View menu, click C/AL Code.

  3. In the C/AL Editor, in the OnAction trigger for the action that you created in step 1, add the following code.

    CopyCode image Copy Code
    CODEUNIT.RUN(50001);

  4. Close the C/AL Editor. Close Action Designer.

  5. Select Page Designer. On the File menu, click Save.

  6. In the Save window, select Compiled, and then click OK.

Expand image Enabling Microsoft Dynamics NAV 2009 for Debugging

To debug an action on a page, you must enable Microsoft Dynamics NAV 2009 for debugging.

To enable Microsoft Dynamics NAV 2009 for debugging

  1. On the computer running Microsoft Dynamics NAV Server, open the CustomSettings.config file. This file is typically located at %programfiles%\Microsoft Dynamics NAV\60\service.

  2. Change the value of the EnableDebugging key to true:

    CopyCode image Copy Code
    <add key="EnableDebugging" value="true" />

  3. Save and close the CustomSettings.config file.

  4. In Control Panel, click Administrative Tools, and then click Services to open the Services snap-in.

    Note Note

    If you are running Windows Server 2003, then you click Administrative Tools, and then click Component Services.

  5. In the list of services, right-click Microsoft Dynamics NAV Server, and then click Restart.

Expand image Viewing the C# Files

When you start the RoleTailored client with debugging enabled, C# files for every RoleTailored client object are generated. You can view these C# files in Visual Studio.

To view the C# files

  1. Start the RoleTailored client.

    Note Note

    The first time that you start the RoleTailored client with debugging enabled, C# files are generated for every RoleTailored client object. Therefore, it takes longer to start the RoleTailored client. The C# files remain on the disk until the Microsoft Dynamics NAV Server service is restarted. We recommend that you set the value of the EnableDebugging key to false after you finish debugging.

  2. Start Visual Studio.

    Note Note

    On a computer running Windows Vista with User Access Control enabled, you must start Visual Studio with administrator privileges. To do this, click Start, right-click Microsoft Visual Studio, and then click Run as administrator.

  3. In Visual Studio, open the Codeunit50001.cs file. To find the location of the C# files, do the following:

    1. Click Start, point to All Programs, point to Administrative Tools, and then click Event Viewer.

      Note Note

      If you are running Windows Server 2003, then you click Start, point to Administrative Tools, and then click Event Viewer.

    2. In the Application log, find the entry that has MicrosoftDynamicsNAVServer for its Source and has the following description:

      Service: <service name>

      Source files for debugging are available under <source file location>

Expand image Attaching Visual Studio to the Microsoft Dynamics NAV Server Service

Before you start debugging, you must attach Visual Studio to the Microsoft Dynamics NAV Server service.

To attach Visual Studio to the service

  1. In Visual Studio, on the Debug menu, click Attach to Process.

  2. In the Attach to Process window, select the Show processes from all users check box and the Show processes in all sessions check box.

  3. Under Available processes, select Microsoft.Dynamics.Nav.Server.exe from the Available Processes list.

  4. Above the Available Processes list, next to Attach to, click Select.

  5. In the Select Code Type window, select Debug these code types, select Managed from the list of code types, and then click OK.

    Note Note

    Debugging T-SQL code types is not supported. If you attach the debugger to T-SQL code while the RoleTailored client is running, then the client does not respond. If you attach the debugger to T-SQL code and then start the RoleTailored client, then you get an error that is similar to the following:

    The following SQL Server error or errors occurred:

    2812,"42000",[Microsoft][ODBC SQL Server Driver][SQL Server]Could not find stored procedure 'sp_sdidebug'.

    5703,"01000",[Microsoft][ODBC SQL Server Driver][SQL Server]Changed language setting to us_english.

    0,"01000",[Microsoft][ODBC SQL Server Driver]SQL Debugging disabled

    5701,"01000",[Microsoft][ODBC SQL Server Driver][SQL Server]Changed database context to 'master'.

  6. In the Attach to Process window, click Attach.

Expand image Adding a Breakpoint to the Codeunit and Running the Code

You use Visual Studio to set breakpoints and step through the C# code.

To add a breakpoint and run code with the breakpoint set

  1. In Visual Studio, right-click the following line of code, point to Breakpoint, and then click Insert Breakpoint.

    CopyCode image Copy Code
    Ok = myCustomer.Target.ALFindFirsts(DataError.TrapError);
    Note Note

    If you have not run the application after the C# files were generated, then you will get the following warning: The breakpoint will not currently be hit. No symbols have been loaded for this document. This warning means that the C# file is not associated with the application in memory. You can ignore the warning. When you run the application to debug, you will hit the breakpoint.

  2. In Visual Studio, right-click the following line of code, point to Breakpoint, and then click Insert Breakpoint.

    CopyCode image Copy Code
    NavDialog.ALMessage(new Guid(50001, 0, 39167, 3, 5, 0, 0, 131, 107, 210, 210), @"Debug test");

  3. In the RoleTailored client, in the navigation pane, click Customers to go to the Customer List page.

  4. On the Related Information menu, under Customer, click Debug Test. The focus changes to the Visual Studio window, and the line of code with the breakpoint is selected.

  5. Right-click myCustomer in the line of code, and then click Add Watch.

  6. On the Debug menu, point to Windows, point to Watch, and then click Watch1.

  7. In the Watch 1 window, expand myCustomer, and then expand Fields to view the values of the fields of the record in the Customer table. Before the line of code runs, the record has not been retrieved and the fields are blank.

  8. In Visual Studio, on the Debug menu, click Continue. The code runs until it hits the second breakpoint. Notice that after the record is found, the fields of the MyCustomer variable in the Watch 1 window are populated with the values from the record.

  9. In Visual Studio, on the Debug menu, click Continue. Focus returns to the RoleTailored client, and the message window appears.

Expand image See Also

Concepts

Debugging C/AL Code


Debugging with Microsoft Dynamics NAV Debugger

Debugging with Microsoft Dynamics NAV Debugger

Microsoft Dynamics NAV provides an integrated debugger to help you check, correct, or modify code so that your application can build successfully and run as expected. You use the integrated debugger to debug applications that run on the Classic client. To debug applications that run on the RoleTailored client, use Visual Studio.

The Debugger

The basic concept in debugging is the breakpoint, which is a mark that you can set on a statement. When the program flow reaches the statement, the debugger intervenes and suspends execution until you instruct it to continue. Without any breakpoints, the code would just run normally when the debugger is active. The state disabled breakpoint means that the breakpoint is still present on the statement but is momentarily disabled (execution will not stop at this breakpoint).

If you wish to determine the cause of a run-time error, you can disable the Breakpoint on Triggers setting from within the debugger and click Go. The debugger will automatically stop execution of the code when it encounters an error.

You can also use the debugger to find a logical error. However, finding the error will not be as easy, and you must have a good understanding of how the code is supposed to work. The debugger enables you to execute your C/AL code one statement at a time while you inspect the contents of global variables, local variables, and text constants at each step. This enables you to see whether the values that are actually used differ from the values that you expected when you designed the application.

The Breakpoint on Triggers setting (SHIFT+CTRL+F12) is enabled by default when you activate the debugger for the first time. Otherwise the code would be executed normally because there are no breakpoints. The debugger will suspend execution of the code when it reaches the first trigger. At this point, you can set other breakpoints and then disable the Breakpoint on Triggers option. If you do not disable the Breakpoint on Triggers setting, the debugger will suspend execution of the code at every trigger it reaches.

See Also

Concepts

Syntax Errors
Run-Time Errors
Program-Logic Errors
Debugging With Visual Studio


Activating the Debugger

Activating the Debugger

Microsoft Dynamics NAV provides an integrated debugger to help you check, correct, or modify code so that your application can build successfully and run as expected.

Activate the Debugger

You can activate the debugger from Microsoft Dynamics NAV and from Classic Application Server.

To activate the debugger from Microsoft Dynamics NAV, click Tools, click Debugger, and then click Active. You can also start Microsoft Dynamics NAV with the debugger active from the command line. To do this, use the debug parameter: fin.exe debug.

To activate the debugger from Classic Application Server, you need include the debug parameter at start-up. For example:

nas debug,startupparameter=”test”,servername=PC0123

If you deactivate the debugger, you cannot activate it again unless you terminate Classic Application Server and then start it with the debug parameter.

Note Note

To be able to activate the debugger, there must be a developer license file in the Classic Application Server installation folder.

See Also

Concepts

Debugging with Microsoft Dynamics NAV Debugger


The Debugger Interface

The Debugger Interface

The debugger interface provides special menus, windows, and a dialog box.

Debugger Menus

The following debugging commands are in the Edit, View, and Debug menus.

Menu Description

Edit

From this menu, you can access the Breakpoints dialog box. It displays a list of the breakpoints that you have set for the object that you are debugging. You can enable, disable, and remove breakpoints in the list.

View

This menu contains commands that display the various debugger windows, such as the Variables window and the Call Stack window. It also contains a command for adjusting the size of the text shown in the interface, and a command to show/hide the standard and debug toolbars.

Debug

This menu contains the following commands which start and control the debugging process:

  • Go executes code from the current statement until a breakpoint or the end of the code is reached, or until the application pauses for user input.

  • Step Into executes statements one at a time so you can decide how to continue after each statement. The execution will step into any function that is called, which means that the debugger will step through each of the statements in the function.

  • Step Over executes statements one at a time, Step Into. However, if you use this command when you reach a function call, the function is executed without the debugger stepping through the function instructions. If you use this command when the Breakpoint on Triggers setting is enabled, the debugger will still suspend code execution at every trigger. If there is a breakpoint in one of the functions that you step over, the debugger will break at that breakpoint.

  • Show Next Statement shows the next statement in your code.

The Debug menu also contains commands for setting, enabling, disabling, and removing breakpoints. The Breakpoint on Triggers option is set independently of other breakpoints, so the Remove All Breakpoints command does not affect it.

See Also

Concepts

Debugging with Microsoft Dynamics NAV Debugger
Activating the Debugger


The Debugger Windows

The Debugger Windows

There are four specialized windows for displaying debugging information: Output, Variables, Call Stack, and Watch. You can access these windows from the View menu and from the standard toolbar.

The Windows

The following windows display debugger information.

Window name Description

Output

Displays information related to the debugging process.

Variables

Displays name, value, and type information for variables used in the current and previous statements, including the values of an array structure. This window has four tabs: All, Locals, Globals, and Text Constants. You cannot add variables to the Variables window (you must use the Watch window for that). You can expand or collapse the variables shown using the tree controls. You can expand a variable if it has a plus sign (+)in the Name field. If there is a minus sign (–) in the Name field, the variable is already fully expanded.

Call Stack

Displays the stack of function calls that are currently active. When a function is called, it is pushed onto the stack. The debugger displays the currently executing function at the top of the stack and older function calls below that. When you double-click a call stack line, a green arrow appears to the left of the line. In the window that contains the code being debugged, a corresponding green arrow indicates how far the debugger has reached in the specific trigger for the call stack line that you selected.

Watch

Use the Watch window to monitor variables of special interest while debugging your program. You can use a drag-and-drop operation to move the name of the variable that you want to watch from the Variables window or from the window that contains the code being debugged. You can also type the names of variables in this window.

The Watch window contains three tabs: Watch1, Watch2, and Watch3. You can group variables that you want to watch together on the same tab. For example, you could put variables related to a specific window on one tab and variables related to a dialog box on another tab. You could watch the first tab when debugging the window and the second tab when debugging the dialog box.

See Also

Concepts

Debugging with Microsoft Dynamics NAV Debugger
Activating the Debugger
The Debugger Interface


Breakpoints

Breakpoints

You can use the F9 key to toggle between breakpoint settings, enable or disable commands and remove breakpoints in the C/AL Editor. You can also select Tools, and then Debugger, and then the Toggle Breakpoints menu command. Information about the breakpoints is stored in the Breakpoints virtual table when you close the C/AL Editor.

The Breakpoints Virtual Table

The Breakpoints virtual table (ID 2000000059), can store information about the breakpoints that you set. The following table lists the fields in the Breakpoint virtual table.

Field | Description
Object ID | The ID of the object for which breakpoint information has been stored.
Object Type | The table, form, page, report, dataport, or codeunit.
Trigger Line | The number of the trigger line where there is a breakpoint.
Code No. | A code number for the trigger that contains a breakpoint. This number is used to identify the trigger at run-time.
Trigger Name | The name of the trigger where there is a breakpoint.
Object Name | The name of the object.
Enabled | A check mark indicates whether the breakpoint is enabled.

You must create a tabular form based on the Breakpoints virtual table to manage breakpoints. Information about breakpoints is saved when you close an object or when you save a new object—compilation is not needed. Breakpoints are not stored for objects that you do not save.

Storing Breakpoints in an XML File

Breakpoints that are stored in the Breakpoints virtual table are automatically stored in a NaviBP.xml file. By default, this file is located in the same folder as the fin.zup file. On a Windows XP computer, the path is: C:\Documents and Settings\user\Application Data.

The following is an example of an XML file that contains breakpoint information for two objects.

<?xml version="1.0" ?>

<BreakpointList>

<Object Type="Codeunit" ID="2" Name="MyCodeunit1"

<Object Type="Codeunit" ID="3" Name="MyCodeunit2"

</BreakpointList>

This file contains breakpoints for MyCodeunit 1 and MyCodeunit 2. The objects are shown as XML elements. called "Object". The object element has three attributes: Type, ID, and Name.

If you expand the first object, MyCodeunit 1, you can see one "Breakpoint" element. This shows that the object contains one breakpoint.

<?xml version="1.0" ?>

<BreakpointList>

<Object Type="Codeunit" ID="2" Name="MyCodeunit1">

<Breakpoint>

<TriggerName>OnRun</TriggerName>

<CodeNo>6</CodeNo>

<TriggerLine>12</TriggerLine>

<Enabled>No</Enabled>

</Breakpoint>

</Object>

<Object Type="Codeunit" ID="3" Name="MyCodeunit2"

</BreakpointList>

When a breakpoint element is expanded, you can see the following types of information for the breakpoint.

XML tag | Description
TriggerName | The name of the trigger that contains the breakpoint.
CodeNo | The code number for a specific trigger in an object. This number is used to identify the trigger at run-time.
TriggerLine | The number of the line in the trigger where the breakpoint has been defined.
Enabled | A Boolean expression to determine whether the breakpoint is enabled.

Starting Microsoft Dynamics NAV or Classic Application Server Using Another Breakpoint File

You can start both Microsoft Dynamics NAV and Classic Application Server with a breakpoint parameter. This enables you to specify a particular file for saving and loading breakpoints, for example: FIN.EXE breakpoints=C:\MyBreakpoints.xml.

Storing Debugging Information in the FIN.ZUP File

The selections that you make in the menu commands are stored in the fin.zup file. This means, for example, that if the debugger was active and set to break on triggers when you logged off, these selections will apply when you log on again.

See Also

Concepts

Debugging with Microsoft Dynamics NAV Debugger
Activating the Debugger
The Debugger Interface
The Debugger Windows
Shortcut Key Overview


Shortcut Key Overview

Shortcut Key Overview

This topic provides an overview of the shortcut keys that are available for the Microsoft Dynamics NAV debugger.

Shortcut Keys

Shortcut key | Command
SHIFT+CTRL+F11 | Debugger active
F5 | Go
F9 | Toggle breakpoint
SHIFT+CTRL+F12 | Breakpoint on triggers
SHIFT+F9 | Open the Breakpoints dialog box
CTRL+SHIFT+F9 | Remove all breakpoints
F8 | Step into
CTRL+F8 | Step over
ALT+NUM* | Show next statement
SHIFT+F5 | Stop debugging
Note Note

A command buffer is used to improve performance. However, when you run the debugger, the command buffer is deactivated.

See Also

Concepts

Debugging with Microsoft Dynamics NAV Debugger
Activating the Debugger
The Debugger Interface
The Debugger Windows
Breakpoints


Using Zoom

Using Zoom

In the Classic client, you use the Zoom feature on a form to view all fields for the current record that are in the table on which the form is based. For example, if you open a sales order form, click the Tools menu, and then click Zoom, then the Sales Header - Zoom window opens. The Sales Header - Zoom window shows all fields in the Sales Header table and the value of each field for the current record.

Troubleshooting with Zoom

You can use the Zoom feature in the Classic client to help you troubleshoot and debug issues. For example, if you create a new form and need to troubleshoot the data that is displayed on the form, then you can use the Zoom feature to view all fields for the current record.

See Also

Tasks

How to: View All Table Fields for a Record in the Classic Client
How to: View All Table Fields for a Record in the RoleTailored Client
How to: Assign Permission to Use Zoom and About This Page

Concepts

Using About This Page and About This Report


How to: View All Table Fields for a Record in the Classic Client

How to: View All Table Fields for a Record in the Classic Client
See Also

You use the Zoom feature on a form to view all fields for the current record that are in the table on which the form is based.

To view field values

  1. In the Classic client, open the form for which you want to view table field values.

  2. On the Tools menu, click Zoom.

    The Zoom window displays every field that in the table on which the selected form is based. It also displays the value of each field for the selected record.

See Also

Tasks

How to: View All Table Fields for a Record in the RoleTailored Client
How to: View and Export the Dataset for a Report

Concepts

Using Zoom


How to: Assign Permission to Use Zoom and About This Page

How to: Assign Permission to Use Zoom and About This Page

The default roles that are provided with the Classic client and the supplemental roles that are provided for the RoleTailored client do not include permissions to run Zoom, About This Page, or About This Report. To add permissions to run Zoom, About This Page, and About This Report, you add the Zoom permission to a role and assign users to that role.

Adding the Zoom Permission

To add the Zoom permission to a role

  1. In the Classic client, on the Tools menu, click Security, and then click Roles.

  2. In the Roles window, select the role to which you want to add the Zoom permission, click Role, and then click Permissions.

  3. In the Permissions window, click All Objects.

  4. In the Permissions (All Objects) window, locate the line for the Zoom permission. This line has the following values.

    Field Value

    Object Type

    System

    Object ID

    5330

    Object Name

    Tools, Zoom

  5. In the Run Permission field of the line for the Zoom permission, select Yes, and then click OK.

    The Zoom permission is now listed in the Permissions window for the role that you selected.

Next Steps

After you add the Zoom permission to a role, you must assign users to that role. For more information, see How to: Assign Users to Roles.

See Also

Concepts

Maintaining Users, Roles, and Permissions
About Users
About Roles


Using About This Page and About This Report

Using About This Page and About This Report

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

In the RoleTailored client, you can view additional information about pages and reports.

To see more information about a page, use the About This Page feature to view all the fields that make up the current page. These fields are the fields for the current record in the table on which the page is based. For example, if you open a sales order form, click the Help button, and then click About This Page, the About This Page: Sales Order window opens. The About This Page window shows the following FastTabs:

  • Page Information

  • Table Fields, sorted first by key fields, then alphabetically

  • Source Expressions

  • FlowFilter Fields

  • Filters

To see more information about a report, use the About This Report feature to view the dataset on which the report is based. For example, if you view the report preview of the Inventory Cost and Price List report, then the first time that you click the Help button and then click About This Report, you activate the About This Report feature. After the feature is activated, if you view the report preview, click the Help button, and then click About This Report, then the About this Report: Inventory Cost and Price List page opens.

Note Note

The About This Report feature remains active during the RoleTailored client session. When the feature is active, the size of the data that is sent to the client when you run a report is about twice the size of the data when the feature is not active. To deactivate the feature, restart the RoleTailored client.

Troubleshooting with About This Page and About This Report

You can use the About This Page and About This Report features in the RoleTailored client to help you troubleshoot and debug issues. For example, if you create a new page and need to troubleshoot the data that is displayed on the page, then you can use the About This Page feature to view all the fields for the current record, including filters that were set by the user and FlowFilter fields.

Exporting About This Page Information

You can export the About This Page information to the following formats:

  • HTML attachment in a new e-mail message

  • Microsoft Word document

  • Microsoft Excel spreadsheet

You can also print the About This Page information directly from the About This Page window.

See Also

Tasks

How to: View All Table Fields for a Record in the RoleTailored Client
How to: View and Export the Dataset for a Report

Concepts

Using Zoom


How to: View All Table Fields for a Record in the RoleTailored Client

How to: View All Table Fields for a Record in the RoleTailored Client
See Also

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

You use the About This Page feature to view all fields for the current record that are in the table on which the page is based.

To view field values

  1. In the RoleTailored client, open the page for which you want to view table field values.

  2. Click the Help button, and then click About This Page.

    The About This Page window displays every field that is in the table on which the selected page is based. It displays both visible and invisible fields. It also displays the value of each field for the selected record.

To export field values

  1. In the RoleTailored client, open the page for which you want to view table field values.

  2. Click the Help button, and then click About This Page.

  3. On the About This Page page, click Actions, point to Send To, and then click one of the following options to send the field data to another format:

    • Recipient as Attachment (HTML format)

    • Microsoft Word

    • Microsoft Excel

  4. (optional) On the About This Page page, click Actions, and then click Print Page to open the Print window and send the About This Page information to a printer.

See Also

Tasks

How to: View All Table Fields for a Record in the Classic Client
How to: View and Export the Dataset for a Report

Concepts

Using Zoom


How to: View and Export the Dataset for a Report

How to: View and Export the Dataset for a Report

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

In the RoleTailored client, you use the About This Report feature to view the dataset on which the report is based. Before viewing the dataset for the first time, you must activate the About This Report feature. To deactivate the feature, restart the RoleTailored client.

Note Note

The About This Report feature remains active during the RoleTailored client session. When the About This Report feature is active, the size of the data that is sent to the client when you run a report is about twice the size of the data when the feature is not active.

To activate the About This Report feature

  1. In the RoleTailored client, open the report for which you want to view the dataset.

  2. To activate the feature, do one of the following steps:

    • In the request page for the report, click the Help button, and then click About This Page.

    • In the request page for the report, click Preview. On the Print Preview page, click the Help button, and then click About This Report. If the About This Report feature was not previously active, then the About This Report window will display the following message:

      The About This Report feature is now active. Run your report again to view the dataset.

To view the dataset from the preview page

  1. Activate the About This Report feature.

  2. In the RoleTailored client, open the report for which you want to view the dataset.

  3. In the request page for the report, set any filters on the report data, and then click Preview.

  4. On the Print Preview page, click the Help button, and then click About This Report.

    Note Note

    The data in the About This Report page will be filtered based the filters that you set in the request page.

To export the dataset from the preview page

  1. Activate the About This Report feature.

  2. In the RoleTailored client, open the report for which you want to export the dataset.

  3. In the request page for the report, set any filters on the report data, and then click Preview.

  4. On the Print Preview page, click the Help button, and then click About This Report.

    Note Note

    The data in the About This Report page will be filtered based the filters that you set in the request page.

  5. On the About This Report page, click Actions, point to Send To, and then click one of the following options to send the field data to another format:

    • Recipient as Attachment

    • Microsoft Word

    • Microsoft Excel

  6. (optional) On the About This Report page, click Actions, and then click Print Page to open the Print window and send the About This Report information to a printer.

See Also

Tasks

How to: View All Table Fields for a Record in the RoleTailored Client

Concepts

Using About This Page and About This Report
Using Zoom


Code Coverage Tool

Code Coverage Tool

The code coverage functionality is useful when you are customizing Microsoft Dynamics NAV and want to test your work. It provides a quick overview of the objects for which code has been executed, and it displays the code that has been logged.

When you add the function (trigger) with ID 6 to Codeunit 1, the Code Coverage menu item appears on the Debugger submenu of the Tools menu. When users select the menu item, the trigger code must open a form. From here, they must be able to start and stop the logging of code. They must also be able to view the code that was logged.

The Code Coverage Overview Window

You access the code coverage functionality from the Debugger submenu of the Tools menu and you can start and stop code logging. You can also view the code that is logged. Further, you can use the CODECOVERAGELOG function to start and stop the logging of code. This function can also retrieve the current logging status.

The Code Coverage window displays the objects (tables, forms, reports, dataports, or codeunits) for which code has been executed and logged during one or more transactions. The Code Overview window displays code for the object that you selected in the Code Coverage window. Lines of code that were executed during the transactions are shown in black. Lines of code that were not executed are shown in red.

The Code Overview window displays code in a similar way to the debugger. However, while you see code being executed in the debugger, the Code Overview window shows you the end result, the code that has been executed. When a line of code is executable, a bullet symbol is shown to the left of the line. Only the information for lines that are marked with a bullet is correct. The lines of code that are not marked with a bullet are simply displayed in the color of the neighboring code lines.

Note Note

You should not modify objects while using the Code Coverage tool because this will produce inconsistent results.

See Also

Tasks

How to: Use the Code Coverage Tool


How to: Use the Code Coverage Tool

How to: Use the Code Coverage Tool

The code coverage functionality is useful when you are customizing Microsoft Dynamics NAV and want to test your work. It provides a quick overview of the objects for which code has been executed, and it displays the code that has been logged.

To use the Code Coverage Tool

  1. In the Classic client, click Tools, click Debugger, and then click Code Coverage to open the Code Coverage window.

  2. Click Start. The Code Coverage tool is now ready to log code.

  3. Return to the Code Coverage window when you have completed the transactions that you want to monitor. This window now contains a list of any tables, forms, reports, dataports, and codeunits that were used.

  4. Click Stop.

  5. Select an object that you want to view the code for. Click Code to open the Code Overview window.

See Also

Concepts

Code Coverage Tool


Extending Microsoft Dynamics NAV Using COM

Extending Microsoft Dynamics NAV Using COM

This section describes how you can extend C/AL by using Component Object Model (COM) technologies. C/SIDE supports Automation servers by acting as an Automation controller and using OCXs (custom controls).

See Also

Tasks

Walkthrough: Receiving Events in C/SIDE
Walkthrough: Using Custom Controls from C/SIDE

Concepts

COM and C/SIDE Overview
Using COM Technologies in C/SIDE
How to: Create an Automation Controller in C/SIDE
Acquiring Controls


COM and C/SIDE Overview

COM and C/SIDE Overview

This topic describes how you can use Component Object Model (COM) technologies in C/SIDE to extend the functionality of Microsoft Dynamics NAV 2009. In C/SIDE, you can use two types of COM technologies: Automation and custom controls.

Automation

Automation is a client-server infrastructure that allows one application to access and communicate with another application. With Automation, an application, such as Microsoft Office Word, exposes its internal functions and routines as Automation objects that Microsoft Dynamics NAV 2009 can access through an Automation controller in C/SIDE. The application that exposes the Automation object, such as Word, acts as the Automation server, and the C/SIDE Automation controller acts as the client.

Automation allows for tasks that are normally run manually to be run automatically instead. For example, you can write a script to extract data from a database, put the data into a Microsoft Office Excel workbook, and then display the data graphically.

For examples of Automation in Microsoft Dynamics NAV 2009, see Walkthrough: Using Automation to Write a Letter in Microsoft Office Word and Walkthrough: Using Automation to Create a Graph in Microsoft Excel.

Custom Controls

Custom controls are OLE Control Extensions (OCX) or ActiveX controls, which are specific types of Automation objects. OCX and ActiveX controls are generally small programs or application objects that that you can invoke from your Microsoft Dynamics NAV 2009 application to perform a specific function or task. You can use custom controls for various types of tasks. By default, there are several custom controls available in Microsoft Dynamics NAV 2009 from the Tools menu in the Classic client. To develop custom controls, you can use tools like Microsoft Visual C++ or Microsoft Visual Basic. Both products use wizards to make it easy to develop COM objects. You can also develop functional controls without understanding the complex details of COM.

If you are going to use existing custom controls from C/SIDE, then you do not need to know anything about COM. Using the functionality provided by a COM object is no different than using any C/AL function.

For an example that uses custom controls, see Walkthrough: Using Custom Controls from C/SIDE.

See Also

Concepts

Extending Microsoft Dynamics NAV Using COM
Using COM Technologies in C/SIDE
Best Practices for Using Automation With the RoleTailored Client


Using COM Technologies in C/SIDE

Using COM Technologies in C/SIDE

C/SIDE supports COM technologies in two ways: using custom controls (OCXs) and as an automation controller.

Limitations

The COM support has the following limitations:

  • Only non-visual controls are supported. A control cannot be used to add graphical elements to a C/SIDE object. For example, you cannot add a third-party control to a form. The control can, however, display information and interact with the user in a window of its own.

  • Exception handling is not supported. C/SIDE does not allow the retrieval of information about exceptions from a control or automation server through the Invoke method of the IDispatch interface and the EXCEPINFO structure.

  • In the Classic Client, it is not possible to invoke the IDispatch from a managed automation server. This is supported in the RoleTailored Client.

Parameters, Return Values, and Data Types

The mechanisms for calling methods in a control, passing parameters, and receiving return values are somewhat complicated. Using tools like the wizards in Microsoft Visual C++ shields you from most of the complexities. However, there is not a one-to-one relationship between the data types that you can use when implementing methods in, for example, Visual C++ and the data types in C/AL. Some of the COM data types are not supported in C/AL and some have a limitation imposed on their usage.

When you use the C/AL Symbol Menu, you can see the syntax for a method or property with the return value and the parameters shown with the COM data types.

Mapping C/AL Data Types to COM Data Types

The following table shows how C/AL data types map to COM data types.

C/AL data type | COM data type | Comment
Boolean Data Type | VARIANT_BOOL (VT_BOOL) |
Option Data Type | long (VT_I4) |
Integer Data Type | long (VT_I4) |
BigInteger Data Type | long (VT_I4) |
Decimal Data Type | CURRENCY (VT_CY) | The CURRENCY type in COM is a special data type with a fixed point that has 15 digits to the left of the decimal point and 4 to the right. The Decimal type in C/AL does not have a fixed point and can have a total of 18 digits. This could lead to rounding being performed when a Decimal type number is passed to a method that expects a CURRENCY. The server changes that number and returns it as a CURRENCY. No matter how many digits the original Decimal had to the right of the decimal point, the returned CURRENCY will have no more than 4 digits.
Char Data Type | BSTR (VT_BSTR) |
Text Data Type | BSTR (VT_BSTR) |
Code Data Type | BSTR (VT_BSTR) |
Date Data Type | DATE (VT_DATE) |
Time Data Type | void (VT_VOID) |
DateTime Data Type | DATE (VT_DATE) |
Automation Data Type | TypedObject, UntypedObject (VT_DISPATCH) |
InStream | VT_STREAM |
OutStream | VT_STREAM |
Variant Data Type | VARIANT (VT_VARIANT) |

Mapping COM Data Types to C/AL Data Types

The following table shows how to map COM data types to C/AL data types.

COM data type | C/AL data type | Comment
VT_UNKNOWN | InStream and OutStream Data Types | Only the IID_IStream and IID_SequentialStream interfaces are supported. If you pass any other IUnknown interface, an error will occur at runtime.
short (VT_I2) | Integer Data Type |
long (VT_I4) | Integer Data Type BigInteger Data Type |
float (VT_R4) | Decimal Data Type |
double (VT_R8) | Decimal Data Type |
CURRENCY (VT_CY) | Decimal Data Type | The CURRENCY type in COM is a special data type with a fixed point, which has 15 digits to the left of the decimal point and 4 to the right. The Decimal type does not have a fixed point and can have a total of 18 digits.
DATE (VT_DATE) | Date Data Type DateTime Data Type | The COM DATE type contains both a date and a time value. C/AL has Date and Time as separate data types. Therefore, the time part of a COM DATE type will be lost when the COM DATE type is mapped to the Date C/AL data type. To keep the date and the time, map the COM Date type to the C/AL DateTime data type.
BSTR (VT_BSTR) | Text Data Type |
VARIANT_BOOL (VT_BOOL) | Boolean Data Type |
TypedObject/ UntypedObject (VT_DISPATCH) | Automation Data Type OCX Data Type |
VT_EMPTY | Text Data Type |
VARIANT (VT_VARIANT) | Variant Data Type |

Unsigned char (VT_UI1), SCODE (VT_ERROR), and SAFEARRAY (VT_ARRAY)

You can use the C/AL variant data type to pass unsigned char, SCODE, or SAFEARRAY to another variant that supports these types. You cannot assign them to C/AL data types.

Remarks

When you call a method with a ByRef parameter, the normal C/AL type conversions do not take place. This means, for example, that if the parameter is of type float, you have to use a C/AL variable of type Decimal. You cannot use Integer and have C/AL convert it for you.

Note Note

If the value that you want to pass has the incorrect type, when, for example, it is a value from a database record field, then you can assign it to a C/AL variable of the correct type before calling the COM object method.

You will sometimes see a COM object method or a property in the C/AL Symbol Menu that has type IDispatch. This means that the method or property returns or expects a COM object. In this case, you must use a C/AL Automation variable that has been declared, through the Subtype, to be the correct COM object. You will have to study the documentation for the automation server to gain the necessary information.

You will also see properties and methods that do not have one of the expected types. For example, a method in Microsoft Office Excel can have a return value of type WORKBOOK. This means that the automation server has implemented a USERDEF type. C/SIDE supports USERDEF types in two contexts: IDispatch and Enumeration.

If the USERDEF type is an IDispatch, it means that it is an interface (sometimes also called class or object) with a specific GUID. You will have to use the same object for a return value or parameter. You do this by creating an Automation variable with the correct subtype. For example, Microsoft Excel has a number of methods that return a WORKBOOK variable. This means that you must declare a variable of type Automation and subtype 'Microsoft Excel 8.0 Object Library'.Workbook.

If the USERDEF type is an enumeration, you cannot use the symbolic name, for example, xl3DPie, but instead must use the enumerator, for example, -4102. For Microsoft Office products, you can find this value by using the VBA Object Browser.

See Also

Reference

Automation Data Type
Variant Data Type

Concepts

Extending Microsoft Dynamics NAV Using COM
COM and C/SIDE Overview


How to: Create an Automation Controller in C/SIDE

How to: Create an Automation Controller in C/SIDE

To implement Automation with C/SIDE, you create an Automation controller in C/AL code of your Microsoft Dynamics NAV 2009 object. By using variables that have an Automation data type, an Automation controller implements and run Automation objects from an Automation server. This topic outlines the procedure for creating an Automation controller.

To create an Automation controller that uses an Automation server

  1. Declare the creatable (top-level) interface (class) of the Automation server as a variable of the Automation data type.

  2. Declare all other objects and interfaces (classes) as variables of the Automation data type.

  3. Use the C/AL CREATE function on the variable that you declared in step 1. Do not use the CREATE function on any other variables.

    If you are creating an Automation controller for the RoleTailored client, then you use the CREATE function to specify whether to run Automation objects on the RoleTailored client or on Microsoft Dynamics NAV Server. For more information, see Best Practices for Using Automation With the RoleTailored Client and CREATE Function (Automation).

  4. Use the methods and properties of the Automation server in your C/AL code.

  5. If needed, use the CLEAR function (destroy) for the top-level object. Otherwise, it will be cleared automatically when the variable goes out of scope.

You write most of your code during step 4 by using the methods and the properties of the Automation server. The syntax and the semantics of these methods and properties are documented in the documentation for each Automation server. Using these methods and properties in C/AL does not require any new or changed syntax.

For examples of creating an Automation controller, see Walkthrough: Using Automation to Write a Letter in Microsoft Office Word and Walkthrough: Using Automation to Create a Graph in Microsoft Excel.

See Also

Concepts

Extending Microsoft Dynamics NAV Using COM
Using COM Technologies in C/SIDE
COM and C/SIDE Overview


Best Practices for Using Automation With the RoleTailored Client

Best Practices for Using Automation With the RoleTailored Client
See Also

With Automation, Windows-based applications, such as Microsoft Office products, expose Automation objects that Microsoft Dynamics NAV 2009 can access and run using an Automation controller in C/SIDE. In the Classic client, Automation objects are always run on the Classic client. In the RoleTailored client, you can choose to run Automation objects either on the RoleTailored client or Microsoft Dynamics NAV Server. By default, the Automation object runs on the RoleTailored client.

Because Automation objects expose a COM interface, Automation can affect both performance and security, depending on whether you run Automation objects on the RoleTailored client or Microsoft Dynamics NAV Server. This topic provides best practices and recommendations to follow when implementing Automation in the RoleTailored client to help limit potential performance and security issues.

Note Note

You specify whether Automation objects run on the RoleTailored client or Microsoft Dynamics NAV Server by using the CREATE Function (Automation) in C/AL code of the object that runs the Automation object.

Automation Object Implementation Overview

Use the following figure and table to help you decide whether to run the Automation object on the RoleTailored client or Microsoft Dynamics NAV Server based on the Automation object's characteristics.

Automation object | RoleTailored client | Microsoft Dynamics NAV Server | Remarks
Native code Automation objects that use out-of-process Automation servers | X |  | This includes Microsoft Office Automation Objects. For more information, see Native and Managed Automation Objects.
Automation objects with a user interface, such as OCX types | X |  | OCX controls cannot run on Microsoft Dynamics NAV Server.
Automation objects that execute as single-threaded apartments | X |  | For more information, see Single-Threaded Apartment and Multithreaded Apartment Automation Objects.
Managed code Automation objects | X | X | Managed code Automation objects can run on either the RoleTailored client or Microsoft Dynamics NAV Server. For more information, see Native and Managed Automation Objects.
Native code Automation objects that use in-process Automation servers | X | X | This includes DLLs, such as MSXML.dll. For more information, see Native and Managed Automation Objects.
Automation objects that execute as multithreaded apartments |  | X | For more information, see Single-Threaded Apartment and Multithreaded Apartment Automation Objects.
Automation objects that stream parameters and are configured to receive events |  | X | You need to install COM objects on the computer running Microsoft Dynamics NAV Server. You also need to install COM objects on the computers running the clients that will use them.

If you choose to run an Automation object on Microsoft Dynamics NAV Server, then see Considerations When Running Automation Objects on Microsoft Dynamic NAV Server.

Single-Threaded Apartment and Multithreaded Apartment Automation Objects

Automation objects can be designed to execute as multithreaded apartments (MTA) or single-threaded apartments (STA).

  • MTA Automation objects are designed for highly reentrant, stressed environments with high throughput for multiple clients. They are most suitable for server-side components.

  • STA Automation objects are designed to provide resource-intensive functionality in a single client environment. For example, the Automation objects of Microsoft Office products are STA-based.

As a best practice, you should:

  • Run STA Automation objects, including Microsoft Office products, on the RoleTailored client.

  • Run MTA Automation objects on Microsoft Dynamics NAV Server.

You can run an STA Automation object on Microsoft Dynamics NAV Server and an MTA Automation object on the RoleTailored client because the .NET Framework manages marshaling between MTA and STA. However, in doing so, you may decrease performance. Some Automation objects are available in both MTA and STA versions, so you can choose. For example, see the DOMDocument and FreeThreadedDOMDocument Automation objects of the Microsoft XML Core Services (MSXML2) library. To read more about these objects and implications on performance, see the PRB: MSXML Performance Bottleneck in ShareMutex Under Stress Microsoft Support Knowledge Base article.

Native and Managed Automation Objects

The RoleTailored client and Microsoft Dynamics NAV Server both support Automation objects that are created from either native or managed code. Automation in Microsoft Dynamics NAV 2009 uses the common language runtime (CLR), which allows managed code to call unmanaged and native Automation objects. The CLR generates a runtime-callable wrapper (RCW) proxy that implements all interfaces of the underlying Automation object. Additionally, the CLR has a built-in marshaling layer that maps the types between the native and managed domains.

Data Type Mapping Between C/AL, COM, and CLR

The following table lists the type mappings between C/AL, COM, and the corresponding .NET CLR types.

C/AL type | COM type | CLR type
Automation | VT_DISPATCH | System.Object
BigInteger | VT_I8 | System.Int64
Boolean | VT_BOOL | System.Boolean
Char | VT_BSTR | System.Byte
Code | VT_BSTR | System.String
Date | VT_DATE | System.DateTime
DateTime | VT_DATE | System.DateTime
Decimal | VT_CY | System.Decimal
Decimal | VT_R4 | System.Single
Decimal | VT_R8 | System.Double
InStream | VT_STREAM | System.Object
Integer | VT_I2 | System.Int16
Integer | VT_I4 | System.Int32
OCX | VT_DISPATCH | System.Object
Option | VT_I4 | System.Int32
OutStream | VT_STREAM | System.Object
Text | VT_BSTR | System.String
Time | VT_DATE | System.DateTime
Variant | VT_VARIANT | System.Object

Automation objects are late-bound activated, which means that they must implement the IDispatch interface. This allows the reflection API, which represents the classes, interfaces, and objects in the .NET runtime, to invoke members. The RCW recognizes managed Automation objects as being managed objects, and standard CLR reflection invocation takes place. As a result, in-process (DLL) and out-of-process (EXE) Automation behaves identically when the Automation objects are created in a managed language.

Considerations When Running Automation Objects on Microsoft Dynamic NAV Server

The following table includes recommendations to consider when you choose to run an Automation object on Microsoft Dynamics NAV Server.

If... Then…

The Automation object accesses a file

You may need to assign additional permissions to the account under which Microsoft Dynamics NAV Server is running. For more information, see Security.

The Automation object accesses a different computer than the computer running Microsoft Dynamics NAV Server

You may need to assign additional permissions or add exceptions to any firewalls. This allows the account under which Microsoft Dynamics NAV Server runs to work correctly.

The Automation object creates a file

You must use the FILE.DOWNLOAD functions to send the file from your user.

The Automation object consumes a file

You must use the FILE.UPLOAD functions to send the file from your user.

The application runs on both the Classic client and the RoleTailored client

You should use the ISSERVICETIER system function to differentiate code that runs on the Classic client and code that runs on the RoleTailored client. The following example shows how to use the ISSERVICETIER function for creating an Automation object. This example requires that you create the following variables.

Variable | Data type
Result | Boolean
AutomationObject | Automation
CopyCode image Copy Code
IF ISSERVICETIER THEN
    Result := CREATE(AutomationObject, TRUE, TRUE)
ELSE
    Result := CREATE(AutomationObject, TRUE);

Security

Changing the Microsoft Dynamics NAV Server Account

By default, the Microsoft Dynamics NAV Server service runs using the Network Service account. The Network Service account does not have permissions to initiate new processes that are configured in Component Services for Windows. This is done to prevent out-of-process Automation servers from running on Microsoft Dynamics NAV Server. We do not recommend that you change this behavior.

If your scenario requires that you change this behavior, then you should create a new account for the Microsoft Dynamics NAV Server service that has launch and activate permissions on the required Automation servers. Automation processes will be created on the server and remain active until they receive a command to terminate or until Microsoft Dynamics NAV Server is restarted.

Preventing Users from Sharing Automation Processes

One risk with running Automation servers on Microsoft Dynamics NAV Server, which is not a risk when running Automation objects on the RoleTailored client, is that users could potentially share the same Automation process. For example, consider the CREATE Function (Automation) in C/AL code of your Automation controller. If you use the construct CREATE (automationServer, TRUE), then the system will search for all created instances of type automationServer and try to reuse them. This can potentially result in the current process reading data that was created by another user. To prevent this, use the construct syntax CREATE (automationServer, FALSE, FALSE) for Automation servers running on Microsoft Dynamics NAV Server.

This is not an issue when running Automation objects on the RoleTailored client because sharing cannot occur, so reusing Automation server instances is acceptable.

In-Process Automation Objects and OCX Controls

In-process Automation objects and OCX controls always run under the same user account as the RoleTailored client when run on the RoleTailored client or Microsoft Dynamics NAV Server. This is because in-process Automation objects are hosted by the current running process and inherit the security properties of the active user. The behavior is different for out-of-process Automation objects that run on Microsoft Dynamics NAV Server. These objects run under the security context of the service account, such as Network Services.

See Also

Tasks

Walkthrough: Using Automation to Write a Letter in Microsoft Office Word
Walkthrough: Using Automation to Create a Graph in Microsoft Excel

Concepts

COM and C/SIDE Overview
How to: Create an Automation Controller in C/SIDE
Programming Best Practices
Security in the RoleTailored Environment


Walkthrough: Using Automation to Write a Letter in Microsoft Office Word

Walkthrough: Using Automation to Write a Letter in Microsoft Office Word
See Also
CollapseAll image

Automation lets you use the capabilities and features of Microsoft Office products, such as Microsoft Office Word or Microsoft Office Excel, in your Microsoft Dynamics NAV 2009 application. In this walkthrough, you will implement Word Automation from a Customer Card in the Classic client and RoleTailored client. You will set up the Customer Card so that if the customer has bought goods for more than LCY 2,500 during the past year, then the user can click a menu item or action to automatically create a letter in Word that offers the customer 3% discount. The letter will include information about the customer, such as the customer's name and the address, and the name of the contact to whom you will address the letter.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating a template in Word that will be used for Word documents that are created from the Classic client and RoleTailored client with Automation.

  • Creating a codeunit and declaring the Automation variables that are required for using Microsoft Office Word Automation.

  • Writing C/AL code in the codeunit to instantiate the Automation object that creates a Word document from a template.

  • Adding C/AL code to the Automation codeunit to transfer data from a table record to a Word document.

  • Calling the Automation codeunit from a menu item on a form or an action on page.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Microsoft Office Word 2007 or Microsoft Word 2003.

Where to Get the Information for the Letter

Most information that you need to transfer to Word is in the Customer table. The Customer table contains a FlowField called Sales (LCY) that contains the aggregated sales for the customer. For this walkthrough, you are learning about Automation, so you use the existing value. In a real customer installation, you would need to set up an appropriate date filter to get the sales for the past year only.

You also need to retrieve the information about your own company that you will use in the letterhead and in the greeting of the letter. This information is contained in the Company Information and User tables.

Where to Place Automation Code

You put all code in a separate codeunit that is called from a menu item on the Customer card. You must consider the following issues when you are deciding where to place the code that uses Automation:

  • The Automation server must be installed on the computer that compiles an object that uses Automation. If you must recompile and modify an object on a computer that does not have the Automation server installed, then you must modify the code to compile it again. We recommend that you isolate code that uses Automation in separate codeunits.

  • Performance can be an issue if extra work is needed to create an Automation server with the CREATE system call. If the Automation server is to be used repeatedly, then you will gain better performance by designing your code so that the server is created only once instead of making multiple CREATE and CLEAR calls).

These two issues may clash, and you will have to make some tradeoffs that are based on the actual context in which your code will be used. In this walkthrough, you are not putting the Automation code on the customer card but are isolating it in a separate codeunit. Performance can be improved by putting the code on the Customer card because you do not have to open and close Word for each letter that is created in the session.

You can work around this problem. If Word is already open when it is called from the code, then the running instance is reused. You can manually open Word or do not close Word after creating the first letter.

Using Word in This Example

You will extract and transfer data one customer at a time. You also will initiate this processing and the subsequent processing in Word from the customer card. This approach to mail merge is different from a mail merge that you can achieve with C/ODBC, which is better suited for bulk processing when creating a large number of letters.

You will insert fields into the Word template and give these fields convenient mnemonic names that correspond to the names of the C/SIDE record fields that you are using.

To make this work, your C/AL code must make two extra calls to Microsoft Office Word. You must call the ActiveDocument.Fields.Update method before using the fields. After you have transferred all the information, you must call the ActiveDocument.Fields.Unlink method. This ensures that you can successfully use the Word fields as placeholders.

In addition, while you can name the fields Customer or Address, you must reference them by indexing into the Fields collection of the document. This can make the C/AL code harder to understand.

Expand image Creating the Word Template for Use by Automation

First, you create a Word template that you will use to create letters to customers that qualify for a discount. To create the template, you add mail merge fields for displaying data that is extracted from Microsoft Dynamics NAV 2009 that you want included in the customer letter, such as the customer's name, contact, and total sales.

To create the template

  1. Open Word and create a new document.

  2. Click where you want to insert the fields.

    • In Word 2007, on the Insert tab, in the Text group, click Quick Parts, and then click Field.

    • In Word 2003, on the Insert menu, click Field.

  3. In the Categories list, select Mail Merge.

  4. In the Field names list, select MergeField.

  5. In the Field Name box under Field Properties, type Contact. This field will display the name of your contact person at the customer site as taken from the Customer table.

  6. Repeat steps 2 through 5 to add the remaining fields as follows:

    Field name Description Underlying table

    Name

    The name of the customer.

    Customer

    Address

    The address of the customer.

    Customer

    Sales (LCY)

    The total amount that the customer has purchased from you.

    Customer

    Company Name

    The name of your company.

    Company Information

    User Name

    The name of the person generating this letter.

    User

  7. Save the Word document as a template with the name Discount.dot at C:\Documents and Settings\All Users\Templates or a folder of your choice.

Expand image Creating the Codeunit and Declaring the Variables

The next step is to create the codeunit that calls Word and creates the letter.

To create the codeunit

  1. In Object Designer, click Codeunit, and then click the New button to create a new codeunit.

  2. On the View menu, click Properties to open the Properties window of the codeunit.

  3. In the TableNo field, click the AssistEdit button to open the Table List window.

  4. In the Table List window, select the Customer table, and then click OK.

To declare the variables

  1. On the View menu, click C/AL Locals, and then click the Variables tab.

  2. On a blank line, type wdApp in the Name field and set the Data Type field to Automation.

  3. In the Subtype field, click the AssistEdit button. The Automation Object List window is displayed.

  4. In the Automation Server field, click the AssistEdit button.

  5. In the Automation Server List, select Microsoft Word 12.0 Object Library if you are running Word 2007 or Microsoft Word 11.0 Object Library if you are running Word 2003, and then click OK.

  6. From the list of classes in the Automation Object List, select the Application class, and then click OK.

  7. Repeat steps 2 through 6 to add the following two Automation variables:

    Name Data type Subtype Class

    wdDoc

    Automation

    Microsoft Word 11.0 or 12.0 Object Library

    Document

    wdRange

    Automation

    Microsoft Word 11.0 or 12.0 Object Library

    Range

  8. Add the following variables.

    Name Data type Subtype Length

    CompanyInfo

    Record

    Company Information

    UserID

    Record

    User

    TemplateName

    Text

    250

Expand image Writing the C/AL Code

Before you start writing the C/AL code that uses Automation, you must do some initial processing. You start by calculating the Sales (LCY) FlowField. Then, you check whether the customer qualifies for a discount. Finally, you retrieve the information from the Company Info and User tables that you use to fill in some of the fields in the letter.

To write the C/AL code

  1. In the C/AL Editor, enter the following lines of code.

    CopyCode image Copy Code
    CALCFIELDS("Sales (LCY)");
IF ("Sales (LCY)" < 2500) THEN
  EXIT;
CompanyInfo.FIND;
UserInfo.GET(USERID);

  2. To create an instance of Word before using it, enter the following line of code.

    CopyCode image Copy Code
    CREATE(wdApp, FALSE, TRUE);

    This statement creates the Automation object with the wdApp variable.

    • The first Boolean parameter in the statement (FALSE) tells the CREATE function to try to reuse an already running instance of the Automation server that is referenced by Automation before creating a new instance. If you change this to TRUE, then the CREATE function always creates a new instance of the Automation server.

    • The second Boolean parameter in the statement creates the Automation object on the client. This is necessary to use this codeunit on a page in the RoleTailored client.

    If you do not use this codeunit in the RoleTailored client, then you can use the statement CREATE(wdApp); instead. For more information, see CREATE Function (Automation).

  3. Enter the following lines of code to add a new document to Word that uses the template that you designed earlier. If required, replace C:\Documents and Settings\All Users\Templates with the correct folder path to the template that you defined in the procedure Creating the Microsoft Office Word Template for Use by Automation.

    CopyCode image Copy Code
    TemplateName := 'C:\Documents and Settings\All Users\Templates\Discount.dot';
wdDoc := wdApp.Documents.Add(TemplateName);
wdApp.ActiveDocument.Fields.Update;

    Because the Add method of the Documents collection requires that you pass the path to the template by reference, you must set up the TemplateName variable to hold this information. You will get a compilation error if you put the path into the call as a literal string.

    The Documents property returns a Documents collection that represents all open documents. You can also see that the Documents collection object has an Add method, and that the Add method has the following syntax.

    expression.Add(Template, NewTemplate, Document Type, Visible)

    expression is a required argument, and it must be an expression that returns a Documents object. All the arguments are optional. You will use Template to open a new document that is based on your template.

    For the syntax in the C/AL Symbol Menu, note that the Documents property returns an object of type DOCUMENTS, which is a user-defined type. The property returns a Documents class or IDispatch interface. This information helps the compiler perform a better type check during compilation. The following statement can also pass both the compile-time and the run-time type checks.

    wdDoc := wdApp.Documents.Add(TemplateName);

    Finally, the Add method returns a Document class. While you did not need to declare a C/AL variable for the interim Documents class, you have declared a variable for the wdDoc return value,.

    The third line contains a call that must be made to ensure that the template works as intended.

    wdApp.ActiveDocument.Fields.Update;

Expand image Transferring Data to Word

Now you can transfer the actual data from the Customer record to the placeholder fields in the Word document.

You have set up the first three fields in the template so that they can contain the contact, name, and address of the customer and you can transfer the data.

To transfer data to Word

  1. Transfer the data by adding the following lines of code.

    CopyCode image Copy Code
    wdRange := wdAPP.ActiveDocument.Fields.Item(1).Result;
wdRange.Text := Contact;
wdRange.Bold := 1;
wdRange := wdAPP.ActiveDocument.Fields.Item(2).Result;
wdRange.Text := Name;
wdRange.Bold := 1;
wdRange := wdAPP.ActiveDocument.Fields.Item(3).Result;
wdRange.Text := Address;
wdRange.Bold := 1;

    You cannot use the fields directly as variables and make an assignment such as Fields.Item(3) := Address. Instead, you use the Result property of the field. This property returns the result of the field as a range. You place this range in the wdRange Automation variable that you declared.

    You then set the Text property of the range to the desired values, which is the name of your contact person and the name and address of the customer. Finally, you add bold formatting.

    The data you are transferring must be in text format. If it is not in text format, then you get a compilation error. wdRange.Text expects arguments to be of type BSTR, which maps to either Text or Code. This means that any data that is not Text or Code must be converted before it is passed to Word. To convert a field to Text, you use the FORMAT function. All the fields that are transferred in this step are in text format, so no conversion is needed and the FORMAT function is not used. However, in this example, you also need to transfer the Sales (LCY) field, which is a Decimal field. To see how to convert the Sales (LCY) field, go to the next step.

  2. To transfer and format the data from the Sales (LCY) field, add the following code

    CopyCode image Copy Code
    wdRange := wdAPP.ActiveDocument.Fields.Item(4).Result;
wdRange.Text := FORMAT("Sales (LCY)");
wdRange.Bold := 0;

    For more information about the FORMAT function, see FORMAT Function (Code, Text).

  3. To transfer the information from the Company Information and User tables, ad the following code.

    CopyCode image Copy Code
    wdRange := wdApp.ActiveDocument.Fields.Item(5).Result;
wdRange.Text := CompanyInfo.Name;
wdRange := wdApp.ActiveDocument.Fields.Item(6).Result;
wdRange.Text := UserInfo.Name;

  4. To complete the processing in Word, add the following code.

    CopyCode image Copy Code
    wdApp.Visible := TRUE;
wdApp.ActiveDocument.Fields.Unlink;

    The first statement opens Word and shows you the letter that was created. The second statement makes the fields work as placeholders.

  5. Save and compile the codeunit and give it a number and a name. For this walkthrough, use Discount Letter.

    Note Note

    If you are running Word 2007 and you receive an error that states "The variable wdApp::MAILMERGEDATASOURCEVALI is defined more than once", then verify that you have defined the wdApp variable as a local variable, not a global variable.

To-Do List

Although this code will work, you must add a few things to make it complete:

  • We recommend that you do not use a hardcoded template name. You should keep the template name in a table, and the user should select it from a page. You can then have different templates for different types of letters that you want to send to your customers.

  • You should add some error-handling code. For example, the CREATE call fails if the user does not have Word installed or if the installation has been corrupted. You should check the return value of CREATE and give an appropriate message if it fails.

  • The user should get a message if the customer does not qualify for the discount. In the example, the codeunit closes without any message.

Expand image Calling the Codeunit from the Customer Card

The final task is to ensure that you can call the codeunit from the Customer Card form in the Classic client and the Customer Card page in the RoleTailored client.

To call the codeunit from the Customer Card form in the Classic client

  1. Open Object Designer, and then click Form.

  2. Select the Customer Card form, and then click Design.

  3. Right-click the Customer menu button, and then click Menu Items.

  4. Select the last line in the list of menu items, and then click Separator to insert a separator line.

  5. In the next line below the separator line, in the Caption field, type the text Word Letter, which will appear in the menu.

  6. In the Action field, click the lookup button, and then select RunObject.

  7. In the RunObject field, click the lookup button, and then select the codeunit that you have created.

  8. Save and compile the Customer Card form.

To call the codeunit from the Customer card page in the Classic client

  1. Open Object Designer, and then click Page.

  2. Select the Customer Card page and then click Design.

  3. At the bottom of Page Designer, right-click a blank line, and then click Actions.

  4. To add a new action, locate the action container with the subtype set to ActionItems.

  5. Right-click the next line after the ActionItems container, and then click New.

  6. In the Caption field of the new line, type Word Letter.

  7. Set the Type field to Action.

  8. With the new action selected, on the View menu, click Properties.

  9. In the RunObject field, type codeunit Discount Letter.

    Note Note

    If you saved the codeunit that you created in the previous procedure under a different name, then substitute Discount Letter with the name that you used.

  10. Save and compile the Customer Card page.

Expand image Next Steps

The letter that you have just created only contains six fields and no body text. Before you can use this letter in an actual situation, you will need to add some more fields, such as the name and address of your own company, the date, and the currency code, and the main text of the letter. It will also need some formatting to make it look more attractive. If you alter the order in which the fields appear in the template, you must change the numbering of the fields in the codeunit to ensure that the correct data is inserted into the appropriate fields.

Expand image See Also

Concepts

How to: Create an Automation Controller in C/SIDE
Using COM Technologies in C/SIDE
COM and C/SIDE Overview


Walkthrough: Using Automation to Create a Graph in Microsoft Excel

Walkthrough: Using Automation to Create a Graph in Microsoft Excel
See Also
CollapseAll image

In this walkthrough, you will transfer data from the G/L Entry table to Microsoft Office Excel and create a graph. This example shows how to handle enumerations by creating a graph in Excel that shows the distribution of personnel expenses by departments. In the Chart of Accounts, you can see that Total Personnel Expenses is the total of accounts 8700 to 8790. In the Dimension Value table, you can see that there are three departments: ADM, PROD, and SALES. You will create a codeunit that retrieves this data from the G/L Entry table, transfers it to Excel, and creates a graph that is similar to the one that is shown in the following figure:

You will run the codeunit directly from Object Designer. In a real application, you would call it from an appropriate place, such as from a menu in the Chart of Accounts window.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating a codeunit that declares the Automation variables that are required for using Excel Automation.

  • Adding C/AL code to the codeunit to run the Automation object that opens Excel.

  • Adding C/AL code to the Automation codeunit to transfer data from a table record to Excel.

  • Adding C/AL code that creates a graph in Excel.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Microsoft Office Excel 2007 or Microsoft Excel 2003.

Expand image Creating the Codeunit and Declaring Variables

To implement Automation in a codeunit, you define the Automation variables. To define an Automation variable, you specify an Automation server and the Automation object.

To create the codeunit and declare variables

  1. In Object Designer, click Codeunit, and then click the New button to create a new codeunit.

  2. On the View menu, click C/AL Globals.

  3. On the Variables tab, add the following variables:

    Note Note

    For the Automation data type variables, the subtype Microsoft Excel 11.0/12.0 Object Library defines the Automation server, and the class specifies the Automation object of the Microsoft Excel 11.0/12.0 Object Library. Microsoft Excel 11.0 or 12.0 Object Library.

    Name Data type Subtype Class

    GLEntry

    Record

    G/L Entry

    xlApp

    Automation

    Microsoft Excel 11.0 or 12.0 Object Library

    Application

    xlBook

    Automation

    Microsoft Excel 11.0 or 12.0 Object Library

    Workbook

    xlSheet

    Automation

    Microsoft Excel 11.0 or 12.0 Object Library

    Worksheet

    xlChart

    Automation

    Microsoft Excel 11.0 or 12.0 Object Library

    Chart

    xlRange

    Automation

    Microsoft Excel 11.0 or 12.0 Object Library

    Range

  4. Close the C/AL Globals window.

Expand image Adding the Code

Now you add the code for the codeunit.

To add the code

  1. In the C/AL Editor, set the key for the G/L Entry table, and then use SETFILTER to select the accounts by adding the following code.

    CopyCode image Copy Code
    GLEntry.SETCURRENTKEY("G/L Account No.","Business Unit Code",
"Global Dimension 1 Code","Global Dimension 2 Code","Posting Date");
GLEntry.SETFILTER("G/L Account No.",'8700..8790');

  2. Create an instance of Excel by adding the following code.

    CopyCode image Copy Code
    CREATE(xlApp);

  3. Add a new workbook to Excel.

    CopyCode image Copy Code
    xlBook := xlApp.Workbooks.Add(-4167);
xlSheet:= xlApp.ActiveSheet;
xlSheet.Name := 'Personnel Expenses';

    The following describes the code:

    • In the first line, you use the Add method of the Workbooks collection to return a new workbook. The attribute -4167 is the enumerator value of worksheets as they apply to Workbook objects. For more information, see About the Enumerator Value.

    • In the second line, you use the ActiveSheet property of the Application class to ensure that what is done next affects the active sheet of the new workbook.

    • In the third line, you use the Name property to name the sheet.

About the Enumerator Value

In the preceding procedure, the Add method includes the attribute -4167. In the Microsoft Excel Visual Basic online Help, the Add method as it applies to the Workbooks object takes one Template argument, which is of type VARIANT. The description in the Help says:

If this argument is a constant, the new workbook contains a single sheet of the specified type. Can be one of the following: XlWBATemplate constants: xlWBATChart, xlWBATExcel4IntlMacroSheet, xlWBATExcel4MacroSheet, or xlWBATWorkSheet.

Instead of passing xlWBATWorkSheet as the Template argument, you are passing the number -4167. In this case, the Template argument, which is of type VARIANT, is an enumeration. Enumerations are either USERDEF types or not. This is not a USERDEF type, so it looks like a VARIANT in the C/AL Symbol Menu. You have to look in the Microsoft Excel Visual Basic Help to figure out that it is actually an enumeration. Arguments can be constants with names like xl* in Excel, wd* in Word, and ol* in Outlook. In C/SIDE, you cannot use the symbolic name xlWBATWorkSheet. You have to use the enumerator -4167.

To find an enumerator value

  1. Open Excel and do one of the following steps to open the Visual Basic Editor.

    • In Excel 2007, on the Developer tab, click Visual Basic.

      Note Note

      If you do not see the Developer tab, then click the Microsoft Office Button in the upper left corner, and then click Excel Options. In the Popular category, under Top options for working with Excel, select the Show Developer tab in Ribbon check box, and then click OK.

    • In Excel 2003, on the Tools menu, click Macro, and then click Visual Basic Editor.

  2. On the View menu, click Object Browser.

  3. In the Project/Library list in the list box in the upper-left corner of the Object Browser, select Excel.

  4. In the Classes list, select XlWBATemplate.

  5. In the Members of ‘XlWBATemplate’ list, select xlWBATWorkSheet. The value can now be seen in the information pane at the bottom of the Object Browser.

Expand image Transferring Data

To transfer the data, you must calculate the data and transfer the results of the calculation.

To transfer data

  1. In the C/AL Editor, on the codeunit, use SETRange to filter the entries in the G/L Entry table on the Global Dimension 1 Code field. The first department is ADM (Administration). Then, you use CALCSUMS(Amount) to get the sum for the ADM department. To do this, add the following code.

    CopyCode image Copy Code
    GLEntry.SETRANGE("Global Dimension 1 Code", 'ADM');
GLEntry.CALCSUMS(Amount);

  2. To transfer the data to Microsoft Excel, add the following code.

    CopyCode image Copy Code
    xlSheet.Range('A2').Value := 'Administration';
xlSheet.Range('A3').Value := GLEntry.Amount;

  3. Add this code for the PROD and SALES departments:

    CopyCode image Copy Code
    GLEntry.SETRANGE("Global Dimension 1 Code", 'PROD');
GLEntry.CALCSUMS(Amount);
    CopyCode image Copy Code
    xlSheet.Range('B2').Value := 'Production';
xlSheet.Range('B3').Value := GLEntry.Amount;
    CopyCode image Copy Code
    GLEntry.SETRANGE("Global Dimension 1 Code", 'SALES');
GLEntry.CALCSUMS(Amount);
    CopyCode image Copy Code
    xlSheet.Range('C2').Value := 'Sales';
xlSheet.Range('C3').Value := GLEntry.Amount;

  4. Save and compile the codeunit.

Expand image Creating the Graph

The final step is to create the graph. You will use the ChartWizard method to create a 3-D pie chart. This is a fast and simple way to do it. You can more tightly control the design of the graph by setting it up using the methods and properties of the various Chart objects, such as ChartArea and Legend.

To create the graph

  1. In the C/AL Editor, on the current codeunit, define a range for the data in the graph.

    CopyCode image Copy Code
    xlRange := xlSheet.Range('A2:C3');

  2. Add a new chart sheet and give it a name.

    CopyCode image Copy Code
    xlChart := xlBook.Charts.Add;
xlChart.Name := 'Personnel Expenses - Graph';

  3. Create the graph.

    CopyCode image Copy Code
    xlChart.ChartWizard(xlRange,-4102,7,1,1,0,0,'Personnel Expenses');

  4. Use the following optional arguments in the ChartWizard method.

    Argument Description Value in method call

    Source

    The range that contains the source data for the new chart.

    xlRange – The object returned by xlSheet.Range(‘A2:C3’).

    Gallery

    The chart type.

    -4102 – The enumerator for the xl3DPie XlChartType enumeration.

    Format

    The option number for the built-in auto formats.

    7

    PlotBy

    An integer specifying whether the data for each series is in rows or columns.

    1 – The enumerator for the xlRows XlRowCol enumerator.

    CategoryLabels

    An integer specifying the number of rows or columns within the source range that contains category labels.

    1 – There is one row with category labels (the department names).

    SeriesLabels

    An integer specifying the number of rows or columns within the source range that contains series labels.

    0 – There are no series labels in your data.

    HasLegend

    TRUE to include a legend.

    0

    Title

    VARIANT with the title of the chart.

    You pass a string such as ‘Personnel Expenses’.

  5. Make Excel visible by adding the following code.

    CopyCode image Copy Code
    xlApp.Visible := TRUE;

    Excel produces a General Protection Fault error when you close a new Excel worksheet that is created when Excel is invisible. To resolve this, you can make Excel visible immediately after you create a new worksheet. You can also make Excel visible just before you create a new Excel worksheet and then make it invisible again immediately after creating the new Excel worksheet. In this case, you would add the following code.

    CopyCode image Copy Code
    xlApp.Visible := TRUE;
xlBook := xlApp.Workbooks.Open(FileName);
xlApp.Visible := FALSE;

Expand image See Also

Tasks

Walkthrough: Using Automation to Write a Letter in Microsoft Office Word

Concepts

How to: Create an Automation Controller in C/SIDE


Walkthrough: Receiving Events in C/SIDE

Walkthrough: Receiving Events in C/SIDE

In the following walkthrough, you enable C/SIDE to receive events from the Dynamics NAV Communication Component. The Dynamics NAV Communication Component and the bus adapter are installed as part of the NAV Application Server. These two components must be installed before you can implement the following example.

C/SIDE can receive events from the components (automation servers and OCXs) that it controls. When you declare a global variable of data type Automation, you can specify whether you want to receive events. You do so by setting the WithEvents property for the variable to Yes. This automatically generates AL triggers for the events that the component provides. A trigger name consists of the name of the automation variable followed by "::<Event name>." For example, if you declare an automation variable with the name MyEventVar, and the component provides the event MessageReceived(...), the name of the trigger is MyEventVar::MessageReceived(...).

Expand image Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

  • Knowledge of the procedures in Walkthrough: Using Automation to Write a Letter in Microsoft Office Word.

Expand image Receiving Notification of Inbound Documents

In the following example, you create two codeunits: one that enables C/SIDE to receive an event – notification of an inbound stream, and one that enables the client to send the stream. In a real life situation the same client would not both send and receive the stream.

To send and receive streams, C/SIDE depends on the existence of two external components, the Dynamics NAV Communication Component and a socket bus adapter.

Expand image Creating a Codeunit and Declaring the Variables

In this example you begin by creating the codeunit that allows the client to receive the event.

To create a codeunit and declare the variables

  1. In Object Designer, click Codeunit, and then click the New button.

  2. Click View, and then click C/AL Globals.

  3. In the C/AL Globals window, enter CC2 as the name of the first variable.

  4. In the Data Type field, select Automation.

  5. In the Subtype field, click the AssistButton to open the Automation Object List window.

  6. In the Automation Server field, click the AssistButton to open the Automation Server List window.

  7. In the Automation Server List window, select Dynamics NAV Communication Component version 2, and then click OK.The classes of the Dynamics NAV Communication Component are now visible in the Automation Object List window.

  8. Select the class called CommunicationComponent.

  9. Repeat steps 3 to 8 to declare the following variables.

    Variable name Data type Subtype

    SBA

    Automation

    Dynamics NAV Socket Bus Adaptor.SocketBusAdapter

    InMsg

    Automation

    Dynamics NAV Communication Component version 2.InMessage

    InS

    InStream

    txt

    Text

  10. Save the codeunit.

Expand image Setting the WithEvents Property

Now that you have declared the variables for the Dynamics NAV Communication Component and a bus adapter, you must set the WithEvents property for the Dynamics NAV Communication Component to Yes. By doing so, you subscribe to events from the Dynamics NAV Communication Component. This means that C/SIDE can receive notification of any inbound streams.

To set the WithEvents property

  1. Open the C/AL Globals window for this codeunit and select the variable CC2 that you created earlier.

  2. Open the Properties window, click the AssistButton in the Value field of the WithEvents property, and then select Yes.Setting the WithEvents property to Yes automatically creates a trigger in the codeunit for each event that the selected subtype of the global variable provides. In the case of the Dynamics NAV Communication Component, it creates the following trigger. CC2::MessageReceived(VAR InMessage : Automation "''_IDISPATCH")

Creating the Automation Servers

Before you can use the Dynamics NAV Communication Component and a bus adapter, you have to create instances of them. To do this, you use the C/AL function CREATE. To call CREATE, enter the following code in the OnRun trigger of the codeunit.

IF ISCLEAR(CC2) THEN

CREATE(CC2);

IF ISCLEAR(SBA) THEN

CREATE(SBA);

CC2.AddBusAdapter(SBA, 0);

SBA.OpenSocket(8079, ' ');

This code creates an instance of the Dynamics NAV Communication Component and a bus adapter. The bus adapter now uses port 8079 on the local computer.

Writing Code in the Trigger

The next step is to write the code in the MessageReceived trigger that determines what happens when the event occurs. Enter the following code in the MessageReceived trigger.

InMsg := InMessage;

InS := InMsg.GetStream();

WHILE NOT (InS.EOS) DO

BEGIN

InS.READ(txt);

MESSAGE(txt);

END;

InMsg.CommitMessage();

This code locates the input stream and uses the InStream.EOS function to determine whether the input stream has reached the End of Stream (EOS). It then uses the InStream.READ function to read the InStream object. The data is read in binary format. Finally, the code displays the text from the InStream in a message. The InStream.READ function has an optional parameter: InStream.Read(Variable, [Length]), that allows you to specify the number of bytes that you want to read from an InStream object. Save and compile the codeunit.

Note Note

If you delete a global variable to which event triggers are associated, the event triggers and the code they contain are also deleted. Furthermore, if you change the Data Type or Subtype of a global variable, all the event triggers associated with this variable and their code is deleted.

Expand image Event Triggers

When you have enabled C/SIDE to receive events from a component that it controls, for example, an automation server, you should be aware of the following limitations and restrictions. This information is also relevant for component developers. There are certain limitations on the triggers that are automatically generated for the events, which the component provides. Furthermore, incoming data is also subject to certain restrictions.

Limitations on Triggers

The following limitations exist on triggers that are automatically generated for the events:

  • C/SIDE only supports the default outgoing interfaces, that is, the source interfaces, which are defined by the automation variable. If more than one outgoing interface is defined by the automation server for a class, only event triggers for the default outgoing interface are generated in the C/AL code.

  • Function calls can have a maximum of 39 parameters.

  • Prototype text strings for functions can contain a maximum of 1024 characters.

  • The connectable object strategy in COM is used to connect Microsoft Dynamics NAV and the automation server. The Sink object defined in this strategy and implemented in Microsoft Dynamics NAV only supports the IDispatch interface (and IUnknown). It is therefore expected that the automation server calls on IDispatch when executing events.

  • Parameter names are truncated to a maximum of 30 characters.

  • There are no return values on event triggers.

  • The variable name along with "::" and the event trigger name are truncated to a maximum of 30 characters.

Restrictions on Incoming Data

All received data is copied to an internal data type, which can handle any data type that COM allows. No data is lost in this conversion and there is no check for valid C/AL data types. The data remains in this internal data type until it is used inside the trigger. When the data is used, it is converted to the appropriate C/AL data type.

However, if the data type is Variant, no conversion occurs. No data is lost in the conversion and all the required checks are made.

If the conversion cannot be performed successfully, because there is an invalid data type or because the data is outside the range, the event trigger causes an error message to be displayed and terminates execution. If the data is never used in the event trigger, no checks are performed for valid data, data type, and data range.

If a parameter is a VAR parameter (called ByRef) and the data is used inside the event trigger, there is an implicit conversion just before the event trigger returns. A check is made to see if the conversion can be performed. If the conversion cannot be performed, an error message is shown and the event trigger terminates.

Sending the Stream

The next step in this example is to create the codeunit that sends the stream.

To send the stream

  1. In Object Designer, click Codeunit, and then click the New button.

  2. Declare the following variables using the C/AL Globals window.

    Variable name Data type Subtype

    CC2

    Automation

    Dynamics NAV Communication Component version 2.CommunicationComponent

    SBA

    Automation

    Dynamics NAV Socket Bus Adaptor.SocketBusAdapter

    OutMsg

    Automation

    Dynamics NAV Communication Component version 2.OutMessage

    outS

    InStream

  3. In the C/AL Editor for the current codeunit, add the following lines of code to the OnRun trigger.

    CopyCode image Copy Code
    IF ISCLEAR(CC2) THEN
    CREATE(CC2);
  IF ISCLEAR(SBA) THEN
    CREATE(SBA);
CC2.AddBusAdapter(SBA, 0);
OutMsg := CC2.CreateoutMessage('Sockets://localhost:8079');
OutS := OutMsg.GetStream();
OutS := WRITE('Hello world');
OutS := WRITE('Using my first');
OutS := WRITE('NAV Socket bus adapter');

  4. Save and compile the codeunit.

This code creates an instance of the Dynamics NAV Communication Component and a bus adapter. It then creates the OutMessage. If the OutMessage cannot be created it returns NULL.

The ICommunicationComponent::CreateOutMessage function has a destination parameter. This parameter has the following syntax.

Bus adapter type://destination

For example:

Named pipe://myServer/myPipe

Sockets://myserver::portnumber

Message queue://MyMessageQueueServer\MyQueue

The socket bus adapter is used to send the OutMessage to Port 8097. The text of the OutMessage is then specified.

Running and Testing the Example

The last step in this example is to test the codeunits that you have just created.

To run and test the example

  1. Start a Microsoft Dynamics NAV client and open the database that contains the codeunits that you have just created.

  2. In Object Designer, select the codeunit that receives the stream, and then click Run. This is a single instance codeunit and is therefore loaded into memory and stored there.

  3. Start another Microsoft Dynamics NAV client and open the same database.

  4. In Object Designer, select the codeunit that sends the stream, and then click Run.

  5. Switch back to the first client and you should see that it is receiving the stream and displaying the text that you defined earlier in the codeunit that sends the stream.

Expand image See Also

Concepts

Extending Microsoft Dynamics NAV Using COM
How to: Create an Automation Controller in C/SIDE


Walkthrough: Using Custom Controls from C/SIDE

Walkthrough: Using Custom Controls from C/SIDE

Custom controls are also known as OLE controls and ActiveX controls. They have also been called OCXs because they often have the .ocx file name extension. In C/SIDE, the term custom control is used, for example, in the Tools menu. When you want to use a control, you define a variable (global or local) of type OCX and reference the control as the subtype of this variable.

Expand image Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

Expand image About This Walkthrough

In this walkthrough, you will build a simple form that uses the C/FRONT OCX to connect to a server, open a database, open a company, and count the number of records that exist in a table that you specify. This form will have access to the functions and properties supported by the C/FRONT OCX.

Expand image Installing and Registering the Control

A control must be physically installed on the computer before you can use it. But a control must also be registered with the operating system before it can be used.

If the control has been installed physically by copying it to the hard disk, but has not yet been registered, follow this procedure to register the control from within C/SIDE.

To install and register the control

  1. Copy the control from the distribution media to the hard disk. The C/FRONT folder contains a readme.txt file with more information.

  2. Click Tools, and then click Custom Controls to open the Custom Controls window.

  3. Click the Control button, and select Browse to open a standard Windows dialog that you use to locate the OCX that you want to register.

  4. When you have located the control, select it, and then click Open.

  5. The control is now registered. You receive a confirmation message after the registration is complete. Click OK to return to the Custom Controls window and the control you have just added appears in the list.

Expand image Using the Control in C/AL

The control must be declared as either a global or a local variable before you can access its methods and properties from C/AL. After you have done this, you can use the methods and set the properties, and you can see the methods and the properties in the Symbol Menu.

Declaring the Control as a Variable

Next you need to declare the control as a variable.

To declare the control as a variable

  1. In Object Designer, create a new blank form that is not based on any table.

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

  3. In the Name field enter cfront, and in the DataType field select OCX.

  4. In the Subtype field, click the AssistButton to open the Custom Control List window.

  5. Locate the control that you just installed on the list, select it, and then click OK.

  6. Declare the following additional variables.

    Name Data type Length

    TableNo

    Integer

    MyCompany

    Text

    50

    MyDatabase

    Text

    50

    MyServerName

    Text

    50

    Driver

    Option

  7. Select the Driver variable and open the Properties window.

  8. In the Value field of the OptionString property enter NDBCS,NDBCN.

Adding Text Constants

The next step is to create the text constants that this form will use.

To add text constants

  1. In the C/AL Globals window, click the Text Constants tab.

  2. In the Name field, enter text001, and in the ConstValue field enter CRONUS International Ltd. Go to the next line.

  3. In the Name field, enter text002,and in the ConstValue field enter The "%2" table contains %1 records.

  4. Save and close the C/AL Globals window.

Expand image Designing the Form

The first step in designing the form is to add the fields that you want the form to contain.

To design the form

  1. In Form Designer, open Toolbox, and then add four text boxes and two option buttons to the form.

  2. Add labels to the text boxes and the first option button, Name them Server, Database, Company, Table Number, and Server Type, respectively.

  3. Select the server text box, click View, and then click Properties to open the Properties window.

  4. In the Value field for the SourceExpr property, click the AssistButton to open the C/AL Symbol Menu window.

  5. Select MyServerName, ensure that the Paste Arguments check box is not selected, and and then click OK.The text box on the form should now contain the following text. <=MyServerName>

  6. Repeat this procedure for the other three text boxes adding the MyDatabase, MyCompany, and TableNo variables to the corresponding text box.

  7. Select the first option button and in the Properties window enter the following values.

    Property Value

    Caption

    SQL

    SourceExpr

    Driver

    OptionValue

    NDBCS

  8. Select the second option button and in the Properties window enter the following values.

    Property Value

    Caption

    Dynamics NAV

    SourceExpr

    Driver

    OptionValue

    NDBCN

Expand image Adding Code to the Form

Now that you have created the basic form you need to add the code that will make it work. In this example, you will place most of the code in the OnPush trigger of a command button at the bottom of the form.

To add code to the form

  1. Open the form in Form Designer and add a command button to the form.

  2. Select the command button, open the Properties window, and then enter Connect as the Name and the Caption.

  3. Select the command button, click View, and then click C/AL Code to open the C/AL Editor.

  4. In the OnPush trigger, enter the following lines of code.

    CopyCode image Copy Code
    CLEAR(cfront);
cfront.ConnectServerAndOpenDatabase(FORMAT(Driver),MyServerName,'tcp
',MyDatabase,0,FALSE,TRUE,'','');
cfront.OpenCompany(MyCompany);
IF cfront.OpenTable(TableNo,TableNo) THEN
MESSAGE(text002,cfront.RecCount(TableNo),cfront.TableName(TableNo));
cfront.CloseTable(TableNo);
MESSAGE('Table closed');
cfront.CloseCompany();
MESSAGE('Company Closed');
cfront.DisconnectServer();
MESSAGE('Disconnect')
Note Note

To enter the C/FRONT functions, open the C/AL Symbol Menu window and select the method or property that you want to use. Ensure that there is a check mark in the Paste Arguments check box and click OK. The C/FRONT function is then pasted into the C/AL Editor, so all you have to do is adjust the parameters.

This code uses the C/FRONT functions to connect to a server and open a database that you specify in the form. It uses the TCPIP protocol. It then opens the company that you specify in the MyCompany field. Next, it opens the table whose number you specify and counts the number of records that the table contains. It then displays a message showing how many records the table contains. When you click OK in the message window it closes the table, the company, and disconnects from the server.

Note Note

This form only uses Windows Authentication to connect to the server. This is specified in the 7th parameter of the ConnectServerAndOpenDatabase function. If you want to use Database Authentication you must set this parameter to false and enter your user ID and password in the 8th and 9th parameters, respectively.

Handling Exceptions

You cannot use the exception-handling mechanisms that are described in, for example, Using COM Technologies in C/SIDE. The samples in the C/OCX Samples show you how to handle exceptions but only for controls that you create yourself. The C/OCX samples are installed as part of the SDK/C/FRONT installation.

The control has two properties that are used for exception handling: Error and ErrorCode. Every time a method is called, the Error property (a Boolean) is used to flag errors; it is set to true if an error occurred and false if no error occurred. An error is defined by the methods in the control. In the control in the C/OCX Samples, one error is that an arithmetic operation caused numeric overflow, another error is that an illegal (out of range) value was passed as a parameter.

When an error occurs and Error is set to true, the ErrorCode is set to a numeric code that can be used by the caller to decide what action to take (for example to display an appropriate message to the user).

Calls to methods in the control can then be wrapped like this in C/AL.

IF (Fin.Error) THEN

// Do error handling.

ErrorHandlerFunction(Fin.ErrorCode)

ELSE

// Continue processing.

Expand image See Also

Tasks

Walkthrough: Receiving Events in C/SIDE

Concepts

Extending Microsoft Dynamics NAV Using COM
How to: Create an Automation Controller in C/SIDE


Acquiring Controls

Acquiring Controls

In C/SIDE you can either acquire new controls by buying them or developing them yourself.

Buy or Develop Controls

You can buy a third-party control and use it in C/SIDE, as long as the control fits within the restrictions imposed. In short, these restrictions are:

  • Only non-visual controls are supported.

  • Events are not supported.

To develop a control yourself, you need a suitable tool. Currently, the recommended tools are:

  • Microsoft Visual C++ 4.0, or later

  • Microsoft Visual Basic 5.0

There are other tools available, but the tools mentioned here have been tested with C/SIDE. Furthermore, they both have highly efficient wizards that make creating controls much easier.

The controls that are created with the wizards are larger than controls that you can create directly. They also require additional runtime libraries, for example, controls created with the wizards in Microsoft Visual C++ require the Microsoft Foundation Classes runtime library. This is an important consideration when creating controls that are meant to be loaded over the Internet. This is probably less important for controls distributed as extensions to C/SIDE.

See Also

Tasks

Walkthrough: Receiving Events in C/SIDE
Walkthrough: Using Custom Controls from C/SIDE

Concepts

Extending Microsoft Dynamics NAV Using COM
How to: Create an Automation Controller in C/SIDE


General C/AL Programming Format

General C/AL Programming Format

To make it easy to maintain an application, it is important to follow a few strict guidelines when writing C/AL code. This section describes the general rules for:

  • Spacing and indentation

  • Parentheses

  • Comments

  • Symbolic values

  • Parameters

  • Order in expressions

  • Order of variables

In addition, we recommend that you enter all C/AL code as English (United States). If all code is in the same language, then it is easier to maintain the application.

Spacing and Indentation

The following examples show how to use spacing and indentation.

Example

Use exactly one space character on each side of a binary operator, such as assignment or plus.

CopyCode image Copy Code
y := (a + b) / 100;

Example

Do not have a space between a unary operator and its argument.

CopyCode image Copy Code
y := -x;

Example

Refer to multiple dimensions in a record array by using sets of brackets with no space characters between the dimensions.

CopyCode image Copy Code
a[i][j] := b;

Example

Do not use blank lines at the beginning or end of any functions.

CopyCode image Copy Code
PROCEDURE P();
BEGIN
  x := a;
  y := (a + b) / 100;
END;

Example

In general, use an indentation of two character spaces.

CopyCode image Copy Code
IF a <> '' THEN
  Record.TESTFIELD(b);

Example

When you split a C/AL statement into two or more lines, do not align the continuation lines according to user-defined or system-defined variables, functions, field names, object names, and other elements. Instead, indent the continuation lines by two characters. Aligning by variable, function, field name, or object name may look clearer in your program, but the alignment will not hold if the variable name is changed to something shorter or longer. Although the system-defined variable and function names are not likely to change, the rule also applies when using them.

CopyCode image Copy Code
MyVariable :=
  Variable1 + Variable2 * 2 +
  Variable3 * 3;

Example

CopyCode image Copy Code
MyFunction(
  Expression1,Expression2,
  Expression3,Expression4);

Example

CopyCode image Copy Code
ERROR(
  StringExpression,
  Expression1,Expression2,Expression3);

Example

CopyCode image Copy Code
IF NOT
  SETCURRENTKEY(
    aaaaaaaaaa,bbbbbbbbbb,cccccccccc,
    dddddddddd,eeeeeeeeee)
THEN
  SETCURRENTKEY(bbbbbbbbbb,aaaaaaaaaa);

Parentheses

The following examples show how to use parentheses.

Example

Align a left parenthesis in an expression with a corresponding parenthesis on the preceding line.

CopyCode image Copy Code
aaaaaaaaaa :=
  ((xxxxxxxxxxx / yyyyyyyyyyyyy) -
   (1 + zzzzzzzzzz / 100)) *
  100;

Example

Do not use parentheses in a function call if the function does not have any parameters.

CopyCode image Copy Code
PostLine;

Use parentheses only to enclose compound expressions inside compound expressions.

CopyCode image Copy Code
IF Boolean1 AND Boolean2 AND (x = y) THEN
  x := a + b
ELSE
  x := b / (a + b);

Comments

The following examples show how to format comments.

Example

Always start comments with // and one space character. Never use braces ({ and }). To emphasize a comment, put it on a separate line and insert one empty line before it.

CopyCode image Copy Code
x := x + 1;

// Comment
x := x * 2;

Example

If the comment is on the same line as the C/AL code, then add one space character before the comment sign.

CopyCode image Copy Code
x := '....'; // Comment

Symbolic Values

Whenever possible, use the name of the Option for a field instead of just an integer for the value.

Example

CopyCode image Copy Code
Table.Field := Table.Field::Option;

Example

CopyCode image Copy Code
IF Table.Field IN[Table.Field::Option1,Table.Field::Option2] THEN
  EXIT;

Incorrect Example

CopyCode image Copy Code
Table.Field := 1;

Example

Whenever possible, use the name of the Option in the conditional possibilities in a CASE statement.

CopyCode image Copy Code
CASE xxx OF
  xxx::aaa,xxx::bbb:
    x := y;
ELSE
  y := x;
END;

Parameters

Use parameters whenever you need to transfer information to a function.

To use a parameter as an option field, define it in the function. When you call the function, use an integer as parameter in the call.

Example

CopyCode image Copy Code
...
P(0);
...
PROCEDURE P(MyOption : 'Value0,Value1,Value2');
BEGIN
  CASE MyOption OF
    MyOption::Value0:
      x := x * 10;
    MyOption::Value1:
      x := x * 15;
    MyOption::Value2:
      x := x * 20;
  END;
END;

Order in Expressions

The variable that you are operating on or comparing to something else must always come first in expressions.

Example

IF x <> 0 THEN

x := x - 100;

Example

IF (Date < a) OR (Date > b) THEN

Date := c;

Incorrect Example

IF 0 > x THEN

x := x - 100;

Order of Variables

List variables in the following order:

  • Record variables

  • Form variables

  • Report variables

  • Dataport variables

  • Codeunit variables

  • Dialog, file, and BLOB variables

  • Simple variables

Record variables are listed in an order that reflects the hierarchy of the tables used in the database. Base tables come before journals and other nonposted lines and headers, which themselves come before ledger entries and posted lines and headers.

Example

CopyCode image Copy Code
VAR
  GLSetup : Record 98;
  UserSetup : Record 91;
  ItemPostingGr : Record 94;
  Item : Record 27;
  ItemJnlTemplate : Record 82;
  ItemJnlBatch : Record 233;
  ItemJnlLine : Record 83;
  ItemReg : Record 46;
  ItemLedgEntry : Record 32;


Programming Best Practices

Programming Best Practices

This topic describes best practices for developing C/SIDE applications.

Ensuring Simplicity

When you program a solution in C/SIDE, keep it simple. This applies to everything that becomes visible either to other programmers or to any users. The following are a few examples.

  • If the default value for a property is adequate for a certain purpose, then do not make the default value explicit.

  • If a variable can be reset using a statement such as a := 0; then do not use a special C/AL function, such as the CLEAR Function, to reset the variable.

  • If the contents of a record can be copied using a statement such as MyRec := MyRec2; then do not use a special C/AL function, such as the TRANSFERFIELDS Function (Record), to copy the contents.

Activating Objects

If you want to use the value of a field to find a record in a table or if you want to activate an object identified by the field, then ensure that the field contains a value. To do this, use the TESTFIELD Function (Record), as shown in the following example. This produces more informative error messages if the value is zero or blank.

CopyCode image Copy Code
GLEntry.TESTFIELD("Department Code");
Dept.GET(GLEntry."Department Code");
GenJnlTemplate.TESTFIELD("Report ID");
REPORT.RUN(GenJnlTemplate."Report ID")

Setting Properties

To set properties from C/AL, use code that is similar to the following code.

CopyCode image Copy Code
"Customer No.".Visible := TRUE;
Cust.MARK := TRUE;
CurrReport.SHOWOUTPUT := TRUE;

Do not use the following code.

CopyCode image Copy Code
Customer." No.".Visible(TRUE);
Cust.MARK(TRUE);
CurrReport.SHOWOUTPUT(TRUE);

Writing Lookups

When writing lookups in C/AL, do not filter records that the user may want to select. Instead, program the record cursor to be positioned on the most relevant record for the search even though it may not be first on the list. When programming the OnLookup trigger for a field, the code in the field’s OnValidate trigger is not called unless you explicitly call Field.VALIDATE. If errors can occur in the validation, then you must operate on a copy of the Rec variable as shown in the following example instead of directly on the Rec variable.

CopyCode image Copy Code
WITH Cust DO BEGIN
  Cust := Rec;
  Dept.Code := "Department Code";
  IF FORM.RUNMODAL(O,Dept) = Action::LookupOK THEN BEGIN
    "Department Code" := Dept.Code;
    VALIDATE("Department Code");
    Rec := Cust;
  END;
END;

To make Lookup work on a field that has a table relation to a system table, you must always explicitly set the LookupFormID Property on controls that show the field.

Set the LookupFormID Property and DrillDownFormID Property on most tables. You cannot anticipate when a user must activate a Lookup or DrillDown button. For example, if a user creates a report with a filter tab on the table, then the Lookup button on the filter tab will not appear unless the LookupFormID property is set on the table.

Designing Journal Forms

The default order of fields in journals is:

  • Date

  • Document Type

  • Document No.

  • No.

  • Description

  • Amount

The order of fields in ledger entries should be the same. The order of fields in forms, pages, and reports should also be the same.

Laying Out Fields on Forms and Pages

This section contains guidelines for which fields to include on the following forms and pages:

  • Card forms

  • Tabular forms

  • Card pages

  • Worksheet pages.

For each type of forms and pages, consistency is important. Similar pages in the application areas must be composed the same way.

Card Forms and Pages

Some card forms and pages are related to a table that contains only a few fields. It is not hard to create such forms and pages because it is often obvious where to place the fields on tabs in a form or on FastTabs on a page and which fields to promote to the FastTab header. Most card forms and pages are related to tables with many fields.

Many forms pages use several tab or FastTab controls. How many tabs or FastTabs are needed and what to call them are specific to each form and page. The following tab and FastTabs names are commonly used:

  • General, which is the first tab

  • Invoicing

  • Posting

All relevant fields must be included on a card form or page. Even card forms and pages with many tabs have a limited space for fields, so you must carefully consider relevancy. Which fields to include depends on the purpose of each form or page. We recommend using the following guidelines:

  • Always include dimensions, such as department, project, or location.

  • Do not include fields that are automatically filled in and do not need to be changed by the user.

  • Do not place the same field on a form or page twice, even on different tabs.

  • If two or more fields are related according to source or function, then group them.

On which tab or FastTab to place a field depends on the specific form or page. Some tabs and fields are used on many pages. For consistency, place the following fields on the General tab or FastTab:

  • No.

  • Name

  • Search Name

  • Blocked

  • Last Date Modified

  • Other information about the account

Place the following fields on the Posting or Invoicing tab or FastTab:

  • General Business Posting Group

  • General Product Posting Group

  • Posting group from the actual application area

  • Department Code

  • Project Code

Tabular Forms and Worksheet Pages

The information in this section refers to tabular forms and also applies to tabular pages.

In general, all fields are included on tabular forms. Some exceptions are mentioned in the following section. The fields are shown or hidden depending on how relevant they are and what the layout of the form is. You must consider the following points when you create tabular forms:

  • Always include dimensions, such as department or project. The fields should be hidden.

  • Do not include FlowFields on tabular forms unless the form is seldom used or the field is essential. FlowFields are calculated even when they are hidden.

  • Do not include more than about 25 fields on a form, because this can affect performance. Consider carefully which fields, both hidden and visible, that you will include on a form. Because of performance considerations, tabular forms should not include fields that may be informative but cannot be changed, such as Posting Group, Journal Name, Weights, and Source Type.

  • Never include fields that are used internally in the program, such as Closed by Entry No.

  • Use tabular forms for all forms in the Setup menu. Creating these forms does not typically cause problems because they often contain only a code and a few information fields.

Tabular forms such as journals, sales/purchase lines, and ledgers are difficult to create and maintain properly because the related tables contain a lot of functionality and many fields. In an uncustomized application, the same template is used to compose these forms so that they look similar. The following table shows the template. It is divided into sections according to functionality. In each section, the most common field names are mentioned.

Note Note

The table does not include all functionality. Additionally, the order that is indicated in the table does not always indicate the order in forms.

Section Example fields

Dates

  • Posting Date

  • Document Date

Document

  • Entry Type

  • Document Type

  • Document No.

No. (of Account)

No.

Posting Description

Description

Dimensions

  • Department Code

  • Project Code

  • Business Unit Code

  • Location Code

  • Salesperson/Purchaser Code

  • Work Type Code

  • Phase Code

  • Task Code

  • Step Code

Currency

  • Currency Code

  • Exchange Rate

General Posting Setup

  • General Posting Type

  • General Business Posting Group

  • General Product Posting Group

Quantity

  • Quantity

  • Invoiced Quantity

  • Remaining Quantity

  • Unit of Measure Code

Prices/Cost

  • Direct Unit Cost

  • Indirect Cost %

  • Unit Cost

  • Total Cost

  • Profit %

  • Unit Price

  • Total Price

  • Price Group Code

  • Chargeable

    Note Note

    The exact name and order depend on the application area.

Amounts

  • Amount

  • Amount Including VAT

  • VAT Amount

  • Remaining Amount

    Note Note

    Amounts in LCY must follow each amount type.

Balancing Account

Balancing Account Type

Balancing Account No.

Balancing General Posting Type

Balancing General Business Posting Group

Balancing General Product Posting Group

Sales/Purchase and Discount

  • Sales/Purchase (LCY)

  • Profit (LCY)

  • Line Discount %

  • Line Discount Amount

  • Allow Invoice Discount

  • Invoice Discount Amount

Payment Terms

  • Payment Terms Code

  • Due Date

  • Payment Discount Date

  • Payment Discount %

Application

  • Serial No.

  • Applies-To Document Type

  • Applies-To Document No.

  • Applies-To ID

  • Applies-To Item Entry

  • Applies-To Entry

  • Apply and Close (Job)

  • Open

Miscellaneous Information

  • Cost Is Adjusted

  • Cost Posted to G/L

  • On Hold

  • Bank Payment Type

Intrastat

  • Transaction Type

  • Transport Method

  • Country Code

Posting Information

  • Quantity to Ship

  • Quantity Shipped

  • Quantity to Invoice

  • Quantity Invoiced

Audit Information

  • User ID

  • Source Code

  • Reason Code

  • Entry No.

See Also

Concepts

Introduction to C/AL


Naming Conventions

Naming Conventions

Precise and consistent terminology helps the end user work with the application. Rules for naming and abbreviating objects also help developers to understand the base application and develop new features faster. This topic contains guidelines for naming objects, table fields, and variables. These guidelines describe naming conventions in English (United States).

The following general guidelines apply throughout your application:

  • Use existing terminology whenever possible.

  • Name everything in a set of objects in the same language.

  • When you review the terminology in a set of objects, use the Translate Export and Translate Import functions on the Tools menu in the Classic client. Export the text strings to a text file to review them, and then import the text file back into the application.

Visible Named Items

This section describes naming all visible items in an application, such as table fields. This includes all items that are presented to an end user.

  • When you develop in C/SIDE, set the application language to English (United States) so that the Name Property is the same as the caption in English (United States). This will make it easier to upgrade and reuse modifications. The end user sees the value of the Caption Property but not the Name property.

  • You must follow the naming convention both for the name in English (United States) and for the caption in your local language.

  • Two objects of the same type must not have the same name.

  • Each object must be named in a way that leaves no doubt as to what it applies to. For example, an object can be specifically related to customers, items, or resources. Do not give a table the name “Status,” because the word Status is too general and could refer to something in most tables.

Table Objects

Always make the names of table objects singular. The table name corresponds to what one record in the table is called.

Form Objects and Page Objects

The name of a form or a page depends on the form type or page type. Use the singular form of the table name for a card form or page form. Use the plural form of the table name for a tabular form or worksheet page name. This informs end users about the type of form or page that they have selected or that will be presented. If you can access a table with both a card form or page and a tabular form or page, then the form and page names should explicitly describe the types. For example, the Item Card and Item List forms both access the Item table and describe the form types. This tells the user that there is more than one way to access the table. Other form types, such as statistics forms, are given names that are as descriptive as possible.

Report Objects

Make the English caption and name of a report descriptive and do not include abbreviations. End users see the caption of a report object in the following instances:

  • On the request form or page.

  • When they modify a report.

  • When they need to identify an item, such as a sales invoice.

We recommend that you make the caption the same as the heading in the report.

Table Fields

Make the name and caption of a field descriptive. The end user should not need to see the caption in the context of other fields to understand what it is.

Describe the field contents and the field type in the caption. We recommend the following guidelines.

Guideline Examples

Include Date when you include a date field.

Note Note

Do not include Date for a date interval field.

  • Posting Date field

  • Allow Posting From field

Include a percent sign when the field contains a percentage.

Profit % field

Include Quantity or Qty. when you name a quantity field. Replace Quantity with No. when referring to the number of entries.

  • Quantity Shipped field

  • No. Printed field

  • No. of New Records field

Include Amount or Amt. when you name an amount field.

Debit Amount field

Distinguish between amount and cost or price. Cost and price are typically used when naming an amount per unit, while amount is cost or price multiplied by quantity.

  • Unit Cost field

  • Unit List Price field

  • Line Amount field

Omit Amount when you include the following words in the caption:

  • Adj. (LCY)

  • Balance

  • Base

  • Charge

  • COGS

  • Discounts

  • Fee

  • Net Charge

  • Payments

  • Profit

  • Purchases

  • Sales

  • Usage

  • Balance at Date field

  • Additional Fee (LCY) field

  • Additional-Currency Net Change field

Use Amounts instead of Amount in FlowFields.

Invoice Amounts field

Name fields in local currency with the ISO currency code for the country/region in parentheses at the end. If a country/region currency has a symbol, use the symbol instead.

Note Note

In the standard application, the abbreviation LCY, which stands for local currency, is used.

  • Sales (DKK) field

  • Sales (LCY) field in the Cust. Ledger Entry table

  • Sales ($) field

If a field contains parentheses, then put a space before the open parenthesis.

Usage (Price) field

Formulate names for Boolean fields as positive questions or statements.

Cost is Adjusted field

If the primary key of a table is a code, then use Code as the name of the field that contains the code.

When the end user typically uses numeric values as keys, the field is called No. even though the field type is code. The following tables are exceptions where the primary key field is No.:

  • G/L Account

  • Customer

  • Vendor

  • Item

  • Item Group

  • Resource

  • Resource Group

  • Job

  • Purchase Header

  • Sales Header

Code field in the Location table

Base the field name on the related table and its primary key when working with table relations.

The following instances are exceptions:

  • If a field refers to a general ledger account, end the name with Account or Acc. but not with G/L Account No. unless the field refers to the actual general ledger account.

    For example, in table 5813, Inventory Posting Setup, field 6 has the TableRelation property set to the G/L Account table. The primary key of the G/L Account table is No. However, field 6 in table 5813 is named Inventory Account. In table 17, G/L Entry, field 3 has the TableRelation property set to the G/L Account table. In this case, field 3 is referring to the actual general ledger account, so the name of field 3 in table 17 is G/L Account No.

  • If a field has a table relation to a posting group table, then call the field Posting Group.

In table 38, Purchase Header, field 4 has the TableRelation property set to the Vendor table. The primary key of the Vendor table is No., and the name of field 4 in table 38 is Pay-to Vendor No.

Use From or To when referring to a line number in a ledger entry table.

From Entry No. field

Use Starting Date to specify the date from which something is valid. Use Ending Date to specify the date until something is valid.

Starting Date field in the Accounting Period table

Use First to mean earliest. Use Last to mean latest.

Last Sales Inv. No. field

Use Before with an amount before a calculation. Use After with an amount after a calculation.

Amount Added Before field

Form Buttons and Menu Items

Captions for command buttons, menu buttons, and menu items depend on whether the control is used as a routing choice to open another form or as a control to activate something.

When a control is used to open another form, its name signifies the form that the control opens. The first menu button on a card, tabular, or list form normally has the name of the corresponding table. We recommend that you name menu items on the menu button with the second part of the full name of the form that will be opened when a user selects the item.

For example, the caption for a menu button on a Customer card form is "Customer.” The caption for one of the menu items is on the Customer menu button is “Statistics.” The Statistics menu item opens the Customer Statistics form. When option buttons are used on the main menu form with the Border property set to Yes, the caption for these controls is the name of the application module.

When a control is used to activate something, the caption for it must be an imperative verb. An example is a control with the caption Check. If a form has many action controls, then they can be gathered as menu items on one menu button, such as Function or Posting.

Other Named Items

This section describes naming of internal items that are not visible to an end user. Because they are never shown to users, they do not have captions.

Codeunit Objects

The name of a codeunit starts with the object that the codeunit processes. The object is usually a record abbreviated as a variable. You can follow the object name with a dash and a description. Write the description of the codeunit in imperative voice without abbreviations. An example is the Purch-Explode BOM codeunit.

Variables

We recommend the following guidelines for naming variables.

Guideline Examples

Omit spaces, periods, and other characters such as parentheses that make quotation marks around a variable necessary.

GenJnlBatch

Replace currency unit signs such as $ with the corresponding currency unit code.

Note Note

This may not make a variable unique. To be unique, it must be different from the corresponding field name. Also, the variable is not necessarily unique when translated to another language.

AmountUSD

Start variables with uppercase letters.

If a variable is a compound of two or more words or abbreviations, then start each word or abbreviation with an uppercase letter.

Describe the variable usage wherever possible. If possible, start with the table name. In a form for a report, if there are several variables that would otherwise have the same name, then use appropriate prefixes or suffixes to differentiate them.

CustInvDiscAmountLCY, EnteredPostingDate (where the prefix is Entered)

Follow country/region-specific rules for abbreviations.

When you set up table and field variables, give the variable the same name as the table or field as described in the Table Fields section.

If a variable with the same name already exists, then add the number 2 to the variable name. If a variable with this name also exists, then use 3, and so on. Use these numbers only if you cannot establish a unique variable in another way.

CustLedgEntry2, NewCustLedgEntry (better than CustLedgEntry2)

Note that parameters and local variables have their own number series. Do not name a parameter GenJnlLine4 because a global variable named GenJnlLine3 already exists.

To use a variable to store a value temporarily, start the variable name with "Temp".

TempType

Use "Old" and "New" as prefixes for record variables when you have old tables and new tables.

Do not use "x" as a prefix. This is used only in table triggers when the record variable is created automatically by the development environment.

Include "Total" in the name of a variable that is used for totaling.

Use "From" or "To" when copying from or to a table.

Use "Starting" or "Ending" with dates and positions.

Use "First" or "Last" with the first or last record in a table or line in a journal. You can also use it as a flag to indicate that this is the first record that is processed.

FirstOrder

When a variable is a Record, Form, Page, Report, Dataport, XMLport, or Codeunit data type and the object has a name that also functions as a field name or local function name, add the suffix Rec, Form, Page, Report, Dataport, XMLport, or Codeunit.

SourceCodeRec (for a record variable from the Source Code table)

Note Note

Because "Source Code" is the name of a table and the name of a field in other tables, you should not use "SourceCode" for variables that hold the two different types of information.

User-Defined Functions

When you name user-defined functions, start with an imperative verb, such as ApplyCustLedgEntry. Use the following function name prefixes:

  • If the code posts something, then use “Post” as a prefix.

  • If the code makes something, then use “Make” as a prefix.

  • If the code inserts something, then use “Insert” as a prefix.

  • If something is checked, then use “Check” as a prefix.

Form Controls

Do not give a form control a name unless you want to refer to it in your C/AL code. If you name a form control, then add a prefix to the name with the abbreviated name of the associated table or form.

See Also

Concepts

Numbering Conventions


Numbering Conventions

Numbering Conventions

Each object and field in C/SIDE is identified by a number that is stored in its ID Property. This topic describes the numbering system for the development environment. Numbering conventions that are used in the base application and guidelines for objects and fields that are outside the base application are described.

The Numbering System

The objects in C/SIDE are grouped as indicated in the following table.

Object number interval | Description
1 - 9,999 | Base application design area
10,000 - 49,999 | Country/region design area
50,000 - 99,999 | Customer design area
100,000 - 999,999,999 | Microsoft Certified Partner design area
Note Note

Do not use the object numbers 99,000 - 99,999 for objects that you create, even though they are in the customer design area. The training material for Microsoft Dynamics NAV uses these numbers.

The fields in C/SIDE are grouped as indicated in the following table.

Table number | Field numbers | Description
1 - 9,999 | 1 - 9999 | Base application design area
1 - 9,999 | 10,000 - 49,000 | Country/region design area
1 - 9,999 | 50,0000 - 99,999 | Customer design area
1 - 9,999 | 100,000 - 999,999,999 | Microsoft Certified Partner design area
10,000 - 49,999 | 1 - 49,999 | Country/region design area
10,000 - 49,999 | 50,000 - 99,999 | Customer design area
10,000 - 49,999 | 100,000 - 999,999,999 | Microsoft Certified Partner design area
50,000 - 99,999 | 1 - 999,999,999 | Customer design area
100,000 - 99,999,999 | 1 - 9,999 | Microsoft Certified Partner design area
100,000 - 99,999,999 | 10,000 - 49,999 | Country/region design area
100,000 - 99,999,999 | 50,000 - 99,999 | Customer design area
100,000 - 99,999,999 | 100,000 - 999,999,999 | Microsoft Certified Partner design area
Note Note

Do not use the field numbers 99,000–99,999 in tables numbered between 1 and 49,999 for fields that you create, even though they lie in the customer design area. The training material for Microsoft Dynamics NAV uses these numbers.

When a Microsoft Certified Partner buys the insert permissions for a table number interval, such as 200,000–200,099, the partner also gets insert permissions for the same number interval (200,000–200,099) for fields in all other tables. If you create a table in the range for which you have insert permissions, then it is possible to create fields in all field number intervals in the table. However, we recommend that you use only the field numbers that are in the same number interval as the table number interval so that fields in solutions from different partners do not interfere with each other.

Objects

The numbering conventions for objects depend on the object type. Conventions for the following types are described in the following sections:

  • Tables

  • Forms

  • Reports

  • Codeunits

Tables

Table object numbers are not divided into intervals in the base application. Use the first available object number when you create a table. Try to group related tables together.

Forms

Form object numbers are not divided into intervals in the base application. Use the first available object number when you create a form. Try to group related forms together.

Reports

Report objects are numbered in intervals in the base application. The following table displays the interval for each application area.

Report number interval | Application areas
1 - 99 | G/L, including VAT and Consolidation
100 - 199 | Accounts Receivable
200 - 299 | Sales
300 - 399 | Accounts Payable
400 - 499 | Purchases
500 - 599 | Common to both Purchases and Sales, including Exchange Rate
600 - 699 | Requisition
700 - 799 | Item, including Intrastat
800 - 899 | Bill of Materials
900 - 999 | Item Group
1000 - 1099 | Inventory (common to Item, BOM, and Item Group)
1100 - 1199 | Resource
1200 - 1299 | Job
1300 - 1399 | General
1400 - 9899 | Future areas
9900 - 9999 | Utilities

If you create a new report that does not belong in one of the existing application areas or if you create a new report and the area in which it belongs is full, then use a number from a new interval of length 100 and between 1,400 and 9,899.

If a report object can be printed, then it is called a report. Otherwise, it is called a batch job. Reports are numbered starting at the lower end of the interval. Batch jobs are numbered starting at the higher end of the interval with decreasing numbers.

We recommend that you number reports that are almost identical within the application areas with the same two final digits even if the report name is different. For example, the Sales Invoice report in the base application is number 206 and the Purchase Invoice report is number 406. Other examples are the date compression batch jobs for ledger entry tables, which always end with 98, and date compressions for budget entries, which always end with 97. This practice may cause gaps in the numbering sequence, but it helps the developer when adjustments to similar reports elsewhere in the application are needed.

Codeunits

Codeunit object numbers are not divided into intervals in the base application. Use the first available object number when you create a codeunit. Try to group related codeunits together.

The journal posting codeunits follow a pattern that makes it easier to understand a new journal once you are familiar with one group of journal posting codeunits.

A group consists of two parts:

  • Codeunits in the first part post a journal.

  • Codeunits in the second part manage the journals.

Codeunit final digit | Journal posting codeunits
1 | Journal Line-Check
2 | Journal Line-Post
3 | Batch Name-Post
Codeunit final digit | Journal managing codeunits
0 | Journal-Management
1 | Journal-Post
2 | Journal-Post+Print
3 | Journal-Batch Post
4 | Journal-Batch Post+Print
5 | Register-Show Ledger

Codeunits for posting invoices also follow a pattern, which is displayed in the following table.

Codeunit final digit | Sales/Purchase Posting Codeunits
0 | Sales/Purchase Post
1 | Sales/Purchase Post (Yes/No)
2 | Sales/Purchase Post+Print

When you create codeunits for the sales application areas, use the same final digit for similar purchase application areas.

Table Fields

When you assign numbers to new fields in a table, consider whether the table is associated with other related tables. If so, then you may need to also add the fields to these related tables. In this case, the field must have the same field number in all tables. For example, if you add a new field to the Customer table but do not add the field to the Vendor table, then you still must reserve that field number in the Vendor table for the new field from the Customer table. It is easier to maintain the application when the tables look very similar.

Examples of associated tables are:

  • Customer and Vendor tables

  • Journal template tables

  • Batch name tables

  • Journal line tables

  • Sales Header, Sales Shipment Header, Sales Invoice Header, and Sales Credit Memo Header tables

  • Purchase Line, Purchase Receipt Line, Purchase Invoice Line and Purchase Credit Memo Line tables

When you create a new independent table, do not leave gaps in the field numbers.

See Also

Concepts

Naming Conventions
Number Ranges for Text Constants


C/SIDE Fundamentals

A C/SIDE application is composed from eight types of application objects. Each type of application object is created using a tool called a designer.

C/SIDE Fundamentals

The application objects you create using these designers are all based on some general concepts. A fundamental knowledge of these concepts speeds up the C/SIDE application development process.

The topics in this section introduce you to the C/SIDE user interface and present the general concepts in C/SIDE application objects.

See Also

Concepts

C/SIDE User Interface
C/SIDE Applications
Physical and Logical Databases


C/SIDE User Interface

C/SIDE User Interface

In this topic, you are introduced to the C/SIDE user interface and to some of the basic concepts that are relevant to application design such as the different object types.

Designing Application Objects

All C/SIDE applications are based on the following types of application objects.

Application object Description

Table

You use tables to store data. For example, a business application usually contains a customer table that stores information about each customer, such as, their name, address, phone number, and the name of your contact person. Understanding tables is the key to using all the other objects.

Form

You use forms to access the information that is stored in the tables. You use forms when you enter new information and when you view information that already exists in the database.

Report

You use reports to present information. You use filters and sorting to select the data that you want to present in a report.

Dataport

You use dataports to import data from and export data to external text files.

XMLport

You use XMLports to import and export data in XML format.

Codeunit

A codeunit contains user-defined functions written in C/AL code. C/AL is the application language you use to write functions in C/SIDE. The functions that a codeunit contains can be used from the other objects in your application. This helps to minimize application size because the same code can be reused.

MenuSuite

A MenuSuite object contains the set of menus that are displayed in the Navigation Pane.

Page

Pages have the same functionality as forms but are intended to run on the RoleTailored client. A page can be role tailored, to suite a users needs.

Note Note

Every application object is identified by an ID number. However, there are restrictions about which numbers you should use when you create your own application objects. Contact your Microsoft Certified Partner for more information.

See Also

Concepts

The Object Designer


The Object Designer

The Object Designer

The Object Designer is the main tool for developing C/SIDE applications. This tool allows you to do the following:

  • Design new tables, forms, pages, reports, dataports, XMLports, menusuites and codeunits.

  • View existing application objects.

  • Modify existing application objects.

  • Run an application object (with the exception of XMLports, menusuite objects and pages).

Dynamics NAV 2009 Classic client Object Designer

Tools in the Object Designer

The following table lists the tools that are available in the Object Designer.

Tool | Designed for
Table Designer | tables
Form Designer | forms
Page Designer | pages
Report Designer | reports
Dataport Designer | dataports
XMLport Designer | XMLports
C/AL editor | codeunits
Navigation Pane Designer | MenuSuite objects

With the exception of MenuSuite objects, you can work on any number of application objects at the same time, each in its own designer. This means that you can run multiple instances of these designers. For example, if you work on three new forms at the same time, then each form is displayed in its own form designer. You can, however, only run one instance of the Object Designer.

The Object Designer and MenuSuite Objects

When you click the MenuSuite button in the Object Designer, select a MenuSuite object and then click Design, the content of the object is displayed in the Navigation Pane Designer. This is where you modify the content.

When you click the MenuSuite button and then click New, a dialog opens asking you to specify which menu suite level (for example, Developer or Administrator) that you want to create. If you have created a MenuSuite object for each level that you have permissions for, the New button will be disabled. This is because only one MenuSuite object is allowed per level. After you have made a selection, the Navigation Pane Designer opens and you have the appropriate design rights.

Object-Oriented vs. Object-Based

C/SIDE is not object-oriented but object-based. This is an important distinction. In an object-oriented language or environment, a developer can create new types of objects based on the ones already in the system. In Microsoft Dynamics NAV, you can only create objects that are either tables, forms, pages, reports, dataports, XMLports, codeunits, or menu suite objects.

Because there are a limited number of application objects, C/SIDE works faster and more efficiently. Your design work is also easier, because you know exactly what you have to work with. But the greatest benefit is stability. It is actually difficult to create a severe bug in C/SIDE.


C/SIDE Applications

C/SIDE Applications

You use C/SIDE to create accounting and business management applications. A C/SIDE application consists of different types of application objects that are tied together to form a coherent whole.

Application Objects

The different types of C/SIDE application objects are based on some general concepts. Some of these concepts are restricted to one type of application object, but others apply to several types. When you understand these fundamental concepts, you have a good foundation for creating your own applications.

The following table shows what each type of application object is used for.

Application object type | Description | C/SIDE concept
Table | A table is used for storing the actual data. Typically a business application will have a Customer table that stores information such as name, address, phone number, and contact person for each of your customers. | Properties, Fields, Keys, C/AL
Form | A form is used to access the information in your tables. Forms are used both when you enter new information and when you view existing information. | Properties, C/AL, Controls
Report | A report is used to present data that contains summary information. For example, you will use a report to print a list of customers. | Properties, C/AL, Controls, DataItems, Sections, Templates, RequestForm
Dataport | A dataport is used to import and export information to and from other programs, such as a comma-separated file from a spreadsheet. | Properties, C/AL, DataItems, RequestForm
XML port | An XMLport is used to import and export data in XML format. | Properties, C/AL
Codeunit | A codeunit contains user-defined functions written in C/AL code. These functions can be used from the other objects in your application. This minimizes the size of the application because the same code can be reused. | C/AL
MenuSuite | A MenuSuite object contains the menus that are displayed in the navigation pane. | Properties
Page | Pages have the same functionality as forms but are intended to run on the RoleTailored client. A page can be role tailored to suit a users needs. | Properties, C/AL

Description of C/SIDE Concepts

Properties

Properties control the appearance and behavior of the application objects and all their sub-objects. Properties are used to control the appearance of data, specify default values, specify colors, and define relationships.

C/AL

C/AL is the language you use to write functions in C/SIDE. In the previous table, "C/AL" refers to functions written in this language.

Triggers

A trigger is a mechanism that is built into an application object. When certain actions are performed on the application object, the trigger initiates an action. You can add your own C/AL code to the trigger to modify the default behavior of the application object or extend its functionality.

Keys

Keys define the order in which data is stored in your tables. You can speed up searches in tables by defining several keys which sort information in different ways.

Fields

A field is the smallest building block in your database. A field typically stores information such as a name or a number.

Controls

Controls are objects on a form or report that display data, perform actions, or enhance the appearance of the form, such as command buttons and text labels.

Request Form

A request form is a form that is used in a report. Before a report is run, a request form is displayed to let the user specify filters and options for the report.

Template

A template defines the overall layout of a report.

Data Items

A data item is a building block for defining a model of your data when you create a report. You use a hierarchy of data items to define which data the report will contain. A data item represents a table, and when you run a report, the system cycles through the records in the associated table. A data item can have one or more sections.

Sections

A section is a substructure of a data item, where you place controls to display information. You will typically use sections that define the body, header, and footer in your report.

See Also

Concepts

C/SIDE Fundamentals


Physical and Logical Databases

Physical and Logical Databases

In this section, you will learn how the information in your application is structured.

When you use a database, you are not usually concerned with where each piece of data is stored, or what size it is. You just want to be sure that when you refer to a name, for example, the correct value is returned. This is why the C/SIDE database system provides a conceptual representation of data that does not include many details about how the data is stored. An abstract data model is used for this conceptual representation. This data model uses logical concepts (such as objects, their properties, and their relationships), which are much easier to understand.

This section distinguishes between the logical and the physical database. For this topic, the logical database is the structure of the data and the relationships between different pieces of information. There is no information about how these structures and relations are implemented. For the physical database, this topic describes how the structures in the logical database and the search paths between them are implemented. The term database means the logical database, unless indicated otherwise.

What the user sees as a coherent set of information in the C/SIDE database system can be stored in several physical disk files, but this is transparent to the user. The following illustration shows how one logical database can be physically stored on three hard disks but still comprise a single (logical) database.

The following illustration shows the logical database.

One logical database, many physical disk files

The Logical Structures in Your Database

Access to the data is made possible by a well-defined logical organization composed of the following.

Logical structure | Description
Fields | Fields are the smallest logical structure in a C/SIDE database. A field holds a single piece of information, such as a name or an amount. A field can hold one specific type of information. (The C/SIDE database system distinguishes between 17 different types of information.) Fields are assembled into a structure called a record. On its own, a field is not very useful, as it can hold only a limited amount of information. Assembling these small bits of information into records produces a much more flexible "information-holder", which also groups fields that belong together.
Records | A record is a logical structure assembled from an arbitrary number of fields. A record stores a single entry in the database. The fields in a record store information about important properties of the entry. Records are organized in tables.
Tables | A table can be thought of as an N times M matrix. Each of the N rows describes a record and each of the M columns describes a field in the record. Tables are organized in companies.
Companies | A company is the largest logical structure in a C/SIDE database. A company is a sub-database; its primary use is to separate and group large portions of data together. A company can contain private tables as well as tables that are shared with other companies.

The following illustration shows logical structures.

database = largest; field = smallest structure


Designing C/SIDE Applications

Designing C/SIDE Applications

Carefully planning the details of your database application will help ensure that your database has the best possible design. An application that has been properly designed is easier to build and maintain. This section contains guidelines for creating quality applications in C/SIDE using the well-known methodology of analysis, design, and implementation.

Steps in Designing a C/SIDE Database Application

Designing a C/SIDE database application usually includes the following steps.

Understanding the Problem

Be sure you understand the business problem you are trying to solve. You need to know who will be using the application and what they will be trying to accomplish.

Designing the Tables

Begin by designing a data model to determine how the data is stored and how it can be best utilized. The data model determines:

  • Which tables the database must contain.

  • What kind of data you want to store in the fields of each table.

  • How the data in the tables are related to each other.

  • Constraints that are necessary to ensure data integrity.

Designing the Application

When you have designed the database tables, you are ready to begin designing the application itself. Designing the application involves:

  • Designing forms (to enter and retrieve data) and reports (to view and present data).

  • Creating C/AL code to connect the application objects.

These steps depend on each other. When you move from one step to another you often have to rethink some of the decisions you made in the previous step.

See Also

Concepts

Understanding the Business Problem
Designing the Data Model
Designing the Application

© 2010 Microsoft Corporation. All rights reserved.


Understanding the Business Problem

Understanding the Business Problem

To decide which information you should store in the database, you have to understand the purpose of the database and how it will be used.

Involving the End User in the Process

The best way to do this is to talk to the people who will be using it. Involving the end user in this process, as early as possible, helps eliminate problems that can stem from misunderstandings about the purpose of the database. Interviewing the end users will help you understand the tasks they expect the system to perform. Based on this understanding, you can determine the kind of data and thereby the kind of tables, forms, and reports that are necessary for completing these tasks. This will often be the most difficult part of the design process as well as the most important. The usefulness of the entire application depends on whether the tables, forms, and reports have been designed correctly.

Your discussions with the end users will give you insight into the tasks they need to perform. You will then know what information the forms and reports should provide. This does not, however, necessarily tell you how the tables should be designed.

See Also

Concepts

Designing the Data Model
Designing the Application


Designing the Data Model

Designing the Data Model

After you understand the problem that you are trying to solve with your C/SIDE application, the next task is to divide the information that you want to store in the database into basic categories such as customers, products, employees, and so on.

Before you create the tables, you should define a data model. The data model must describe:

  • The tables in the database.

  • The fields in the tables.

  • The relationships between the fields in your tables.

  • Constraints for fields and relationships.

The Entity-Relationship (ER) model is a tool for defining a data model.

An ER model can map real-world situations to a relational database system such as C/SIDE.

An ER model divides all the elements of a real world situation into two categories: entities and relationships. An entity is a "thing" in the real world with an independent existence. An entity may be an object with a physical existence, such as a particular car or person, or it may be an object with a conceptual existence, such as a company or a job. Relationships describe how the entities are related.

To use the ER model, you must complete the following steps:

  1. Identify the types of entities associated with the problem that you are trying to solve. Create tables to represent each of these types of entities.

  2. Identify the properties of each type of entity and create fields in the tables to represent each of these properties.

  3. Identify the relationships between the entities and add these relationships to the tables.

The following topics provide an overview of the ER model and illustrate the benefits of applying a formalized design method.

  • ER Models and C/SIDE

  • Determining Field Types

  • Role of Keys in C/SIDE

  • Determining the Relationships

  • Assuring the Quality of the Design

See Also

Concepts

Understanding the Business Problem
Designing the Application


ER Models and C/SIDE

A real world problem usually contains groups of entity types that are similar. For example, consider a company that has hundreds of customers. All of the customers are entities. These customer entities share the same properties, but each entity will have its own values for the properties. Such similar entities define an entity type, which is a set of entities with the same properties.

ER Models and C/SIDE

When you implement the abstract ER model in C/SIDE, you transform all the abstract elements in your model into concrete representations. Each entity type corresponds to a table in C/SIDE and each of the entity’s properties corresponds to a field in the table.

The following table summarizes how basic ER model concepts relate to C/SIDE concepts.

ER model concept | Corresponding concept in C/SIDE
An entity type | A table
An entity | A record
A property | A field

See Also

Concepts

Determining Field Types


Determining Field Types

Determining Field Types

In the Entity-Relationship (ER) model, after you have identified the entity types and their properties, you must determine the types of values that these properties can have. In C/SIDE, this corresponds to determining the data types of the fields in your tables.

Example

In this example, your analysis using the ER model has revealed that you have an entity type describing your company's customers. You define the following Customer table.

Company Name | Contact Person | Phone | … | Payment Method
… | … | … | … | …

Your analysis shows that you need fields such as Company Name, Contact Person, Phone, and Payment Method. When you create the Customer table, you select the following data types.

Field name | Description | Data type
Company Name | The name of the customer (for example, "CRONUS International Ltd."). | Text
Contact Person | The contact person in the company (for example, "JLJ"). | Text
Phone | The customer's phone number (for example, "45662111"). | Text
Payment Method | The payment method for the customer (for example, "pay in cash"). | Text

For more information about the available data types, see Field Data Types.


Role of Keys in C/SIDE

Role of Keys in C/SIDE

The Entity-Relationship (ER) model places an important constraint on the entities of a particular entity type (records in a table). This is the key or uniqueness constraint on the properties (fields). An entity type usually has at least one property which contains unique values for each entity. This property is used to uniquely identify each record. The following table shows how the ER model concepts are related to C/SIDE concepts.

ER model concept | Corresponding C/SIDE concept
Constraints on the entities of an entity type | Constraints on the records in a table
The uniqueness constraint on entity properties | A key based on fields in a table

The records in a table must be arranged according to some criteria (that is, a key) so that C/SIDE can work efficiently with the data in tables. For example, an Employee table can be ordered according to the employees' social security numbers because this number uniquely identifies each employee.

For a field to be a key for a table, there must be a uniqueness constraint for every record in the table. This constraint prevents any two records from having the same value in the key field. It is not a constraint on a specific record, but a constraint on all the records in the table.

Sometimes, a key consists of several fields. In this case, the combination of the values in all the fields in the key must be unique for each record. Sometimes you can define several keys for a table. For more information about defining keys, see How to: Define Primary and Secondary Keys.


Determining the Relationships

Determining the Relationships

After you have designed tables to store individual types of information, you must determine the relationships in those tables. In your final application you want to retrieve the information in a meaningful way. Usually the information that you retrieve from your database will consist of data stored in several tables. To enable you to get this data, C/SIDE uses relationships to link the tables that contain the related information.

Types of Relationships

Database terminology normally distinguishes between the following types of relationships:

  • One-to-Many

  • Many-to-Many

  • One-to-One

One-to-Many Relationships

In a one-to-many relationship, a record in Table 1 can have more than one matching record in Table 2, but a record in Table 2 can have no more than one matching record in Table 1. This is the most common type of relationship in a relational database.

Many-to-Many Relationships

In a many-to-many relationship, a record in Table 1 can have more than one matching record in Table 2, and a record in Table 2 can have more than one matching record in Table 1. This represents a problem in database design and may signal an inefficient design. Normally, you break down a many-to-many relationship into two one-to-many relationships.

One-to-One Relationships

In a one-to-one relationship, a record in Table 1 can have no more than one matching record in Table 2, and a record in Table 2 can have no more than one matching record in Table 1. This kind of relationship is inefficient and can often be avoided by combining the two tables.


Assuring the Quality of the Design

Assuring the Quality of the Design

When you are defining the tables and setting up relationships, you often have to select from among several possible solutions. To ensure that you select the most appropriate solution, you need a way to measure the quality of your design. You can use the normalization process to do this. The normalization process conducts a series of tests on your design to verify whether it belongs to a certain normal form. There are six normal forms. Most documentation on relational database design explains how to obtain these forms. For more information, see Designing the Application.


Designing the Application

Designing the Application

After you have designed the tables, you are ready to begin work on the application itself. The analysis phase has already given you an overview of the answers that the application is expected to provide. The table design phase has given you a clear understanding of where and how the information will be stored. Based on this understanding, you are ready to begin assembling the entire application.

Assembling Your Application

The following table shows how to assemble the application.

Design process | Description
Creating Forms | Forms are used to present or collect information. You have access to a number of design elements, such as text, data, pictures, lines, and color.
Creating Reports | Reports are used to present data as printed documents. When you want to present summary information, reports are more flexible than forms.
Creating C/AL Codeunits | Codeunits are containers for storing C/AL code. When you put the code into a codeunit, you can reuse the same algorithms many places in your application. This reduces the size of the application and makes it easier to maintain.
Testing and Refining the Application | Before you release your application, you have to analyze your design for errors. This is usually an iterative process. When you have completed all this you will have a useful application. If you took the time to plan all the steps of the application design carefully, you will also have an application that is fully documented. This will be a great help when you need to make adjustments and additions to the application in the future.

Recommended Books about Database Design

The following list shows some books about relational database design:

  • C. J. Date. An Introduction to Database Systems. Addison-Wesley Publishing Co.

  • Elmasri, R. A. and Navate, S. B. Fundamentals of Database Systems. Benjamin/Cummings.

  • Dutka, A. F. and Hanson, H. H. Fundamentals of Data Normalization. Addison-Wesley Publishing Co.

  • Michael J Hernandez, Database Design for Mere Mortals. Addison-Wesley Publishing Co.

See Also

Concepts

Understanding the Business Problem
Designing the Data Model


Testing the Application

Testing the Application

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Before you release your Microsoft Dynamics NAV application you must test the functionality. Testing is an iterative process. It is important to create repeatable tests, and it is helpful to create tests that can be automated. This topic describes the features in Microsoft Dynamics NAV 2009 SP1 that help you test the business logic in your application and some best practices for testing your Microsoft Dynamics NAV application.

Note Note

The features in Microsoft Dynamics NAV 2009 SP1 do not provide assistance for testing the UI in your application.

Test Features

Microsoft Dynamics NAV 2009 SP1 includes the following features to help you test your application:

  • Test codeunits

  • Test runner codeunits

  • UI handlers

  • ASSERTERROR statement

Test Codeunits

You write test functions as C/AL code in the test codeunits. When a test codeunit runs, it executes the OnRun function and then executes each test function in the codeunit, records the outcome in a log, and displays the results in a message window. The outcome of a test function is either SUCCESS or FAILURE. If any error is raised by either the code that is being tested or the test code, then the outcome is FAILURE, and the error is included in the results log.

Even if the outcome of one test function is FAILURE, the next test functions are still executed.

The functions in a test codeunit are one of the following types:

  • Test function

  • Handler function

  • Normal function

For more information, see How to: Create Test Codeunits and Test Functions.

Test Runner Codeunits

You use test runner codeunits to manage the execution of test codeunits and to integrate with other test management, execution, and reporting frameworks. By integrating with a test management framework, you can automate your tests and allow them to run unattended.

Test runner codeunits include the following triggers:

  • OnBeforeTestRun

  • OnAfterTestRun

You can use these triggers to perform pre- and post-processing, such as initialization or logging test results. If you implement the OnBeforeTestRun trigger, then it executes before each test function executes. If you implement the OnAfterTestRun trigger, then it executes after each test function executes and additionally suppresses the automatic display of the results message.

For more information, see How to: Create a Test Runner Codeunit.

UI Handlers

To create tests that can be automated, you must handle cases when user interaction is requested by the code that is being tested. Microsoft Dynamics NAV 2009 SP1 provides UI handlers that run instead of the requested UI. UI handlers provide the same exit state as the UI. For example, a test function that has a FunctionType of MessageHandler handles MESSAGE function calls. If code that is being tested calls the MESSAGE function, then the MessageHandler function is called instead of the MESSAGE function. You write code in the MessageHandler function to verify that the expected message is displayed by the MESSAGE function.

The following table describes the available UI handlers.

Function type | Purpose
MessageHandler | Handles MESSAGE statements
ConfirmHandler | Handles CONFIRM statements
StrMenuHandler | Handles STRMENU statements
FormHandler | Handles specific forms or pages that are not run modally
ModalFormHandler | Handles specific forms or pages that are run modally
ReportHandler | Handles specific reports

You create a specific form handler for each form or page that you want to handle and a specific report handler for each report that you want to handle.

If you run a test codeunit from a test runner codeunit, then any unhandled UI in the test functions of the test codeunit results in a failure of the test. If you do not run the test codeunit from a test runner codeunit, then any unhandled UI displays as normal.

For more information, see How to: Create Handler Functions.

ASSERTERROR Keyword

When you test your application, you should test that your code performs as expected under both successful and failing conditions. To test how your application performs under failing conditions, you can use the ASSERTERROR keyword. The ASSERTERROR keyword specifies that an error is expected at run time in the statement that follows the ASSERTERROR keyword. If a simple or compound statement that follows the ASSERTERROR keyword results in an error, then execution successfully continues to the next statement in the test function. If a statement that follows the ASSERTERROR keyword does not result in an error, then the ASSERTERROR statement itself fails with an error, and the test function that is running produces a FAILURE result.

For more information, see C/AL ASSERTERROR Statements.

Testing Best Practices

We recommend the following best practices for designing your application tests:

  • Separate the test code from the code that is being tested. In this way, you can release the tested code to a production environment without releasing the test code.

  • Test code should test both positive and negative paths of the code that is being tested. The positive path validates that the code being tested works as intended under successful conditions. The negative path validates that the code being tested works as intended under failing conditions.

  • If a test has a SUCCESS result, then the test function should validate the result of application calls, such as return values, state changes, or database transactions.

  • If a test has a FAILURE result, then the test function should validate that the intended error messages are presented and that data has the expected values.

  • Tests should not require user intervention.

  • Test execution and reporting should be fast and capable of integrating with the test management system so that the tests can be used as check-in tests or other build verification tests, which typically run on unattended servers.

See Also

Tasks

How to: Create Test Codeunits and Test Functions


How to: Create Test Codeunits and Test Functions

How to: Create Test Codeunits and Test Functions

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

In Microsoft Dynamics NAV 2009 SP1, you can create test codeunits and create test functions within the test codeunits.

When you create a new function in a test codeunit, the FunctionType property is set to Test by default.

To create a test codeunit and test functions

  1. On the Tools menu, click Options.

  2. In the Options window, in the Show C/AL Testability properties field, enter Yes, and then click OK.

  3. In the Classic client, on the Tools menu, click Object Designer.

  4. In Object Designer, click Codeunit, and then click New.

  5. On the View menu, click Properties.

  6. In the Properties window, in the Subtype field, select Test to specify that this is a test codeunit.

  7. On the View menu, click C/AL Globals.

  8. In the C/AL Globals window, on the Functions tab, enter the names of the test functions in this test codeunit.

  9. For each test function, select the function, click View, click Properties, and then verify that the FunctionType property is set to Test.

  10. If any test functions need UI handlers, then enter the names of the handler functions in the C/AL Globals window. For more information, see How to: Create Handler Functions.

  11. In the C/AL Editor, enter code for each test function and handler function that you defined. You can also enter code in the OnRun function. The OnRun function runs when you execute the codeunit and before the test functions run.

    Note Note

    Test functions must not have parameters or return values.

  12. On the File menu, click Save. In the Save window, verify that the Compiled check box is selected, and then click OK to save and compile the test codeunit.

See Also

Tasks

How to: Create a Test Runner Codeunit
How to: Create Handler Functions

Concepts

Testing the Application


How to: Create Handler Functions

How to: Create Handler Functions

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

In Microsoft Dynamics NAV 2009 SP1, you can create test codeunits and test functions to test your application. We recommend that you create tests that can be automated. To create automated tests, you must write code to handle all UI interactions so that the tests do not require user interaction when running. To do this, you create special handler functions.

The following handler functions are available:

  • MessageHandler

  • ConfirmHandler

  • StrMenuHandler

  • FormHandler

  • ModalFormHandler

  • ReportHandler

Before you begin, you must do the following:

  • Set Show C/AL testability properties to Yes

  • Create a test codeunit and test function

For more information, see How to: Create Test Codeunits and Test Functions.

To create a handler function

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Codeunit, select your test codeunit, and then click Design.

  3. On the View menu, click C/AL Globals.

  4. In the C/AL Globals window, on the Functions tab, enter the name of the new handler function.

  5. On the View menu, click Properties.

  6. In the Properties window, in the FunctionType property, select the type of handler from the drop-down list.

  7. In the C/AL Globals window, on the Functions tab, click Locals to specify the signature of the handler functions. The following table describes the signature that is required for each type of handler function.

    FunctionType Signature

    MessageHandler

    <Function name>(<Msg> : Text[1024])

    ConfirmHandler

    <Function name>(<Question> : Text[1024]; VAR <Reply> : Boolean)

    StrMenuHandler

    <Function name>(<Options : Test[1024]; VAR <Choice> : Integer; <Instruction> : Text[1024])

    FormHandler

    <Function name>(VAR <form name> : Form <form id>)

    ModalFormHandler

    <Function name>(VAR <form name> : Form <form id>; VAR <Response> : Action)

    ReportHandler

    <Function name>(VAR <report name> : Report <report id>)

    The parameters of the functions that are being handled are passed as parameters to the handler functions. Parameters that are specified as VAR are passed by reference to the handler function. The value of the parameter can be changed by the handler function.

    For example, to specify the signature for a ConfirmHandler function, do the following:

    1. In the C/AL Locals window, on the Parameters tab, enter a name for the <Question> parameter. In the DataType field, select Text. In the Length field, enter 1024. Verify that the Subtype field is blank.

    2. Enter a name for the <Reply> parameter. In the Var field, select the check box. In the DataType field, select Boolean. Verify that the Subtype and Length fields are blank.

    3. In the code of the ConfirmHandler function, set the reply that you want to simulate by setting the value of the Reply parameter.

  8. In the C/AL Globals window, select the test function that requires a handler function. For example, a test function that requires a handler function is one that calls some application code, which then calls the CONFIRM function.

  9. On the View menu, click Properties.

  10. In the Properties window for the test function, in the HandlerFunctions property, enter the name of the handler function that this test function will use instead of the UI. For example, if the code tested by this test function calls the CONFIRM function, enter the name of your ConfirmHandler function. To specify more than one handler function, separate the handler function names by a comma.

    Note Note

    Every handler function that you enter in the HandlerFunctions property of a test function must be called at least once in the test function. If you execute a test function that has a handler function listed that is not called, then the test fails.

  11. In the C/AL Editor, enter code for the handler functions that you defined. The code should simulate to the code that is being tested that the UI was actually raised and some values entered or some actions were taken. For example, the code could verify that the expected text is presented. The code should exit with the same state with which the UI would exit.

  12. On the File menu, click Save.

  13. In the Save window, verify that the Compiled check box is selected, and then click OK to save and compile the test codeunit.

See Also

Tasks

How to: Create Test Codeunits and Test Functions
How to: Create a Test Runner Codeunit

Concepts

Testing the Application


How to: Create a Test Runner Codeunit

How to: Create a Test Runner Codeunit

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

In Microsoft Dynamics NAV 2009 SP1, you can create test runner codeunits to manage the execution of test codeunits and to integrate with test management or test reporting frameworks.

To create a test runner codeunit

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. On the Tools menu, click Options.

  3. In the Options window, in the Show C/AL Testability properties field, enter Yes, and then click OK.

  4. In Object Designer, click Codeunit, and then click New.

  5. On the View menu, click Properties.

  6. In the Properties window, in the Subtype field, select TestRunner to specify that this is a test runner codeunit.

  7. In the C/AL Editor, in the OnRun function, enter code to run the test codeunits. For example, the following code in the OnRun function of a test runner codeunit runs three test codeunits.

    CopyCode image Copy Code
    CODEUNIT.RUN(CODEUNIT::CustomerDiscount);
CODEUNIT.RUN(CODEUNIT::TaxCalculationTest);
CODEUNIT.RUN(CODEUNIT::ItemCostingTest);
    Note Note

    You may want to define your test suite in a table and then write code in the OnRun function of the test runner codeunit to iterate through items in the table and run each test codeunit.

  8. (optional) To create an OnBeforeTestRun trigger, do the following steps:

    1. On the View menu, click C/AL Globals.

    2. In the C/AL Globals window, on the Functions tab, on a new line in the Name field, enter OnBeforeTestRun, and then click Locals.

    3. In the C/AL Locals window, on the Parameters tab, enter the following.

      Name DataType Length

      CodeunitID

      Integer

      CodeunitName

      Text

      30

      FunctionName

      Text

      30

    4. In the C/AL Locals window, on the Return Value tab, enter the following.

      Name Return type

      OK

      Boolean

    5. Close the C/AL Locals window.

    6. In the C/AL Editor, in the OnBeforeTestRun trigger, enter code that executes before each test function. Typically, the code in the OnBeforeTestRun function determines if the test function should execute and returns true if it should. Otherwise, the trigger returns false. The OnBeforeTestRun trigger may also initialize logging variables. For example, the following code initializes a logging variable and returns true to indicate that the test function should execute. This example requires that you create the following global variable.

      Name DataType

      Before

      DateTime
      CopyCode image Copy Code
      Before := CURRENTDATETIME;
EXIT(true);

  9. (optional) Do the following steps to create an OnAfterTestRun trigger:

    1. On the View menu, click C/AL Globals.

    2. In the C/AL Globals window, on the Functions tab, on a new line in the Name field, enter OnAfterTestRun, and then click Locals.

    3. In the C/AL Locals window, on the Parameters tab, enter the following.

      Name DataType Length

      CodeunitID

      Integer

      CodeunitName

      Text

      30

      FunctionName

      Text

      30

      Success

      Boolean

    4. Close the C/AL Locals window.

    5. In the C/AL Editor, in the OnAfterTestRun trigger, enter code that executes after each test function. For example, the following code logs the results of the tests to the test reporting system. This example requires that you create a record variable named log.

      CopyCode image Copy Code
      log.INIT;
log.UnitId := CodeunitId;
log.Unit := CodeunitName;
log.Func := FunctionName;
log.Before := Before;
log.After := CURRENTDATETIME;
If Success THEN
  log.Status := log.Status::Success
ELSE BEGIN
  log.Status := log.Status::Failure;
  IF FunctionName <> '' THEN
    log.Message := GETLASTERRORTEXT;
END
log.INSERT(true);
      Note Note

      If you implement the OnAfterTestRun trigger, then it suppresses the automatic display of the results message after the test codeunit runs.

  10. On the File menu, click Save.

  11. In the Save As window, in the ID field, enter 50006. In the Name field, enter TestRunner. Verify that the Compiled check box is selected, and then click OK.

See Also

Tasks

How to: Create Test Codeunits and Test Functions
How to: Create Handler Functions

Concepts

Testing the Application


Walkthrough: Testing Vendor Discount

Walkthrough: Testing Vendor Discount

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Before you release a customized Microsoft Dynamics NAV 2009 application to a production environment, you must test the application. This walkthrough demonstrates how to use the test codeunits and test runner codeunits in Microsoft Dynamics NAV 2009 SP1 to test an application.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Showing C/AL testability properties

  • Creating a test codeunit and test function

  • Adding a test to a test runner codeunit

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 SP1 with a developer license.

  • The CRONUS International Ltd. demo data company.

Expand image Story

Isaac is a business application developer working for CRONUS International Ltd. He has modified codeunit 70, Purch-Calc.Discount, which is a codeunit in the base application. Isaac wants to test the functionality of his customized codeunit before he offers the customized application for sale. He creates a new test codeunit with a new test function to test the Purch-Calc.Discount codeunit.

Isaac has already created several other test codeunits to test other modifications to his application, and he has a test runner codeunit to run these tests. He wants to add the new test for the Purch-Calc.Discount codeunit to the test runner codeunit so that he can run the test automatically with his suite of other tests.

Expand image Showing C/AL Testability Properties

Before he begins creating test codeunits and functions, Isaac must verify that he has specified the option to show the testability properties. Otherwise, he cannot specify that a codeunit is a test codeunit and cannot view the FunctionType or HandlerFunctions properties.

To show C/AL testability properties

  1. In the Classic client, on the Tools menu, click Options.

  2. In the Options window, in the Show C/AL Testability properties field, enter Yes, and then click OK.

Expand image Creating a Test Codeunit and Test Function

Isaac creates a new codeunit and specifies that it is a test codeunit. He creates the test function, which tests the Purch-Calc.Discount functionality, to this test codeunit.

To create the test codeunit and test function

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Codeunit, and then click New.

  3. On the View menu, click Properties.

  4. In the Properties window, in the Subtype field, select Test to specify that this is a test codeunit.

  5. On the View menu, click C/AL Globals.

  6. In the C/AL Globals window, on the Functions tab, enter CalculateVendorDiscount. This is the name of the test function.

    Note Note

    By default, functions that you add to test codeunits have the FunctionType property set to Test.

  7. On the Functions tab, click Locals.

  8. In the C/AL Locals window, on the Variables tab, enter the following variables, which you will use in the CalculateVendorDiscount test function.

    Name DataType Subtype

    VendorDiscount

    Record

    Vendor Invoice Disc.

    PurchaseLine

    Record

    Purchase Line

    Discount

    Decimal

    PurchCalcDisc

    Codeunit

    Purch-Calc.Discount
    Note Important

    Be sure to create these variables on the Variables tab, not on the Parameters tab. If you create them on the Parameters tab, then you get an error when you compile that says the test method signature is invalid.

  9. In the C/AL Locals window, on the Text Constants tab, in the Name field, enter VendorDiscountError. In the ConstValue field, enter Vendor Discount Error - Line Amount: %1, Discount: %2, Discount Amount: %3.

  10. Close the C/AL Locals window and the C/AL Globals window.

  11. In the C/AL Editor, in the CalculateVendorDiscount function, enter the following code.

    CopyCode image Copy Code
    Discount := RANDOM(99) + 1; // Set Discount > 0, <= 100

// Find purchase line.
PurchaseLine.SETFILTER("Line Amount", '>0');
PurchaseLine.SETFILTER("Allow Invoice Disc.", '=%1', TRUE);

IF NOT (PurchaseLine.FINDFIRST) THEN
  ERROR('No Purchase Line found for the Calculate Vendor Discount test');

// Create vendor discount.
WITH PurchaseLine DO BEGIN
  IF NOT (VendorDiscount.GET("Buy-from Vendor No.", "Currency Code", "Line Amount")) THEN BEGIN
    VendorDiscount.INIT;
    VendorDiscount.Code := "Buy-from Vendor No.";
    VendorDiscount.VALIDATE("Currency Code","Currency Code");
    VendorDiscount.VALIDATE("Minimum Amount","Line Amount");
    VendorDiscount.INSERT(TRUE);
  END;
END;

VendorDiscount.VALIDATE("Discount %", Discount);
VendorDiscount.MODIFY(TRUE);

// Run codeunit "Purch.-Calc.Discount" for calculating discount.
PurchCalcDisc.RUN(PurchaseLine);
PurchaseLine.GET(PurchaseLine."Document Type",PurchaseLine."Document No.",PurchaseLine."Line No.");

// Validate purchase discount amount
WITH PurchaseLine DO BEGIN
  IF NOT (ROUND("Line Amount" * Discount / 100) = "Inv. Discount Amount") THEN
    ERROR(VendorDiscountError, "Line Amount", Discount, "Inv. Discount Amount" );
END;

    The code in this test function prepares the test data by setting a random discount amount, getting a record from the Purchase Line table that satisfies two filters, and creating a record in the Vendor Invoice Disc. Table with the random discount amount. Next, it runs the Purch-Calc.Discount codeunit, which contains the code that is being tested. Finally, it validates the results of running the Purch-Calc.Discount codeunit and raises an error if the results are not as expected.

    Note Note

    This test code does not guarantee that the state of the database after you run the test is the same as the state of the database before you run the test.

  12. On the File menu, click Save.

  13. In the Save As window, in the ID field, enter 50005. In the Name field, enter VendorDiscount. Verify that the Compiled check box is selected, and then click OK.

Isaac can now create additional test functions in the VendorDiscount test codeunit to test other aspects of vendor discounts. These test functions should include negative tests, which validate that the code being tested works as intended under failing conditions.

Expand image Adding a Test to a Test Runner Codeunit

Isaac adds a line to his existing test runner codeunit that runs the new VendorDiscount codeunit. The test runner codeunit runs all the test codeunits that Isaac has created to test his customized functionality.

To add a test to a test runner codeunit

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Codeunit, select the existing test runner codeunit, and then click Design.

    Note Note

    If you do not have an existing test runner codeunit, you can create a new one. For more information, see How to: Create a Test Runner Codeunit. You do not need to create the OnBeforeTestRun and OnAfterTestRun triggers for this walkthrough. If you create the OnAfterTestRun trigger, then it suppresses the automatic display of the results message after the test codeunit runs.

  3. In the C/AL Editor, in the OnRun function, add the following code.

    CopyCode image Copy Code
    CODEUNIT.RUN(CODEUNIT::VendorDiscount);

  4. On the File menu, click Save.

Expand image Next Steps

The next steps are:

  • Create additional test codeunits to test different parts of the customized application.

  • Add the test codeunits to the test runner codeunit.

  • Run the test runner codeunit.

If you run the test runner codeunit, then you get a message window that displays the following text:

Test Code Unit 50005 Vendor Discount

CalculateVendorDiscount: SUCCESS

SUCCESS

If you added additional test codeunits or additional test functions, then the message window also displays the results of those tests.

Expand image See Also

Concepts

Testing the Application


Multiuser Environments

Multiuser Environments

This section explains how the Database Management System (DBMS) handles data integrity in a multiuser environment. It describes how the C/SIDE system handles situations where more than one user or process tries to change the same object.

Managing Multiuser Environments

In multiuser environments there are two key areas to consider:

  • Ensuring data integrity in a multiuser environment. For more information, see Ensuring Data Integrity.

  • Locking in Microsoft Dynamics NAV depends on the database option. For more information, see Locking in Microsoft Dynamics NAV.

See Also

Concepts

Development Considerations


Ensuring Data Integrity

Ensuring Data Integrity

Data integrity deals with the reliability of the data stored in the database, that is, the requirement that the database must describe the real world as accurately as possible. All access to the data in your database goes through the DBMS (Database Management System).

Database Management System

The DBMS controls the interaction of the user with the database to ensure that a number of data integrity constraints are observed. By observing these constraints, the DBMS protects your data from damage or corruption. The DBMS is a very complex unit in your database system, but the methods that it uses to maintain data integrity are based on a few fundamental concepts:

  • Write transactions and recovery.

  • Read consistency and concurrency.

  • Table locking.

  • Deadlock detection.

  • Committing updates.

See Also

Concepts

Write Transactions and Recovery


Write Transactions and Recovery

Write Transactions and Recovery

A write transaction in C/SIDE is defined as an atomic unit of work on the database which is either completed entirely or not at all. In other words, a transaction is a way to encapsulate a sequence of read and write operations on the database in order to ensure that either all or none of the operations is performed. The concept of write transactions is a general C/SIDE feature that is used both in single- and multiuser environments.

Ensuring Data Consistency

When a transaction has been submitted to the C/SIDE DBMS (Database Management System), the system is responsible for making sure that:

  • All the transaction operations are completed successfully and their effect is recorded permanently in the database.

    - or -

  • The transaction has no effect on the database. The DBMS must prevent the following situation from occurring: some of the transaction operations are applied to the database while the other operations in the same transaction are not applied. A situation like this could occur if a transaction fails while executing.

Some typical reasons for a transaction to fail are:

  • The user decides to abort the transaction.

  • The transaction cannot be completed because some information is missing.

  • The system crashes, due to hardware or software errors.

  • There are operation errors, such as overflow or division by zero.

If the transaction is aborted, all the tables are restored to the state they were in before the transaction started.

A typical example of a write transaction would be transferring $100 from one account to another. This involves two operations in a single database:

  1. Subtract $100 from account A.

  2. Add $100 to account B.

If a power failure or some other fatal error interrupts the program after the first operation, the database is not in a consistent state, because the second operation has not been completed. However, bundling both operations into a single transaction ensures that either none or both of the operations are executed and the data will always be consistent.

Write Transactions

The previous section explained that the database will always be consistent regardless of whether a transaction is committed or aborted. The way C/SIDE handles write transactions and keeps the database consistent is different from traditional approaches. Traditionally, database systems have a feature that automatically maintains a log file which records all changes to the database. This log file contains images of a record before it is modified and after it is modified—"before" and "after" images. The changes recorded in the log file can be used to recover the database if failures occur.

Assume that an application program aborts because of power failure or is aborted by the operator. The database is now in an inconsistent state, and all the modifications that were already made to the database must be canceled. In common database systems this is achieved by so-called rollback recovery, that is, by backing out the updates of the application program. This rollback is performed by reading the log file backwards and undoing the recorded changes to the database, until the point where the application program started. This restores the modified records to their original contents.

The C/SIDE DBMS does not need to use a log file because the C/SIDE database is data version oriented. This means that each time a transaction is committed, a new version of the database is created. While you enter new data in the database your changes are private; not until you commit the changes, does the new data become public and establish the newest version. The DBMS allows different applications to access and modify the database concurrently by letting them work on individual versions that are snapshots of the database taken at the point in time where the applications start to access the database. The advantages of the data version approach will become clear as you read through the following sections.

See Also

Concepts

Read Consistency and Concurrency


Read Consistency and Concurrency

Read Consistency and Concurrency

C/SIDE is data-version oriented, meaning that each time a write transaction is performed, a new version of the data in the database is created.

Working with data versions makes it possible for many users to access the database without interfering with each other.

Maintaining Read Consistency and Concurrency

The implications of the data-version approach are many; most important is that different applications may be reading different versions of the same database. These versions are snapshots of the database at the time when the application started to access the database. In this way the DBMS allows for concurrency while still maintaining read consistency. If the accesses involve only data retrieval and no changes, then the newest version will persist for all applications. There will be no new version until a write transaction is performed.

When you update the database, your modifications are private and only become public after you commit your updates. Your newly-committed updates plus the part of the database which was not modified make up the newest version.

See Also

Concepts

Write Transactions and Recovery
Data Version
Table Locking
Deadlock Detection
Differences between Commit in C/AL and C


Data Version

Data Version

The data in the database is stored in a data structure that resembles a tree.

A tree data structure consists of nodes. Each node in the tree, except for a special node called the root, has one parent node and one or more child nodes. The root node has no parent. A node that has no child node is called a leaf; a non-leaf node is called an internal node. The level of a node is defined as one more than the level of its parent, with the level of the root node being zero.

C/SIDE Data Structure

The data structure used in the C/SIDE database is called a B+ tree. This means that the tree structure is balanced and that the data (records) are stored only in the leaf nodes, not in the internal nodes. A balanced tree has the advantage that it always contains the minimum number of levels necessary to contain the nodes, so all search paths will be the shortest possible. A B+ tree structure is an efficient data structure that enables fast searches to be performed.

Example

For this example, the tree structure in your database contains a branch with customers A, B, and C, with two free database blocks available.

Assume that you need to modify customer A and C. When you update the records, the DBMS makes a copy of the original. The copies will use two free database blocks. You will then modify the copies, and a new internal node is created.

If an error occurs during the transaction, or the user decides to abort the changes, the database blocks occupied by the copied branch will be freed and be available for new database updates.

If the transaction is committed, this new internal node will replace the old node, and the database blocks used by the old versions of customer A and C will now be available as free database blocks that can be used by database updates.

The database contains a number of historical versions. Gradually, as the free area in the database is consumed by succeeding historical versions, new versions begin to replace the oldest versions.

Slow operations may have performance issues in this environment. Suppose Application X is reading data from the latest version, while generating a very time-consuming report. In the meantime, Application Y begins performing write transactions which consist of order entries.

Newer versions of the database are created as the order entries are added to the database. The maximum number of historical versions in your database depends upon the space in the database that currently is not used by the newest version, that is:

  • The maximum defined size of the database.

  • The amount of space currently used to hold the newest version.

  • Space available for historical versions.

At some point, the data version accessed by X becomes the oldest complete data version. But Y needs a database block from this version to complete its modifications.

This conflict is solved by the DBMS by giving priority to the write transaction and ejecting application X. The following run-time error message is sent to X on the next read operation, "Data version is no longer valid". The process is forced to restart with the newest version. As long as Y continues and the space in the database available for historical versions remains the same, X will most likely not be able to generate the report. To solve this problem, you could expand the size of the database.

See Also

Concepts

Table Locking
Deadlock Detection
Differences between Commit in C/AL and C


Table Locking

In multiuser environments, the DBMS ensures the integrity of the data by setting write locks on all the tables you are updating. This prevents other users from making changes to the same tables.

Table Locking

While write operations automatically lock a table during updates, you can explicitly lock a table, even if you are not performing a write operation. By locking a table immediately before accessing a record, you are assured that the data you might change in the record conforms to the data you have read, even if some time has elapsed. A write lock does not influence data retrieval. This means that locking a table does not prevent other users from gaining read access to the records in the table.

For information on managing locks SQL Server, see Locking in the Database Engine. (for SQL Server 2008) or Understanding Locking (for SQL Server 2005).

In Classic Database Server, a write lock is active until the write transaction is either aborted or committed.

See Also

Concepts

Data Version
Deadlock Detection
Differences between Commit in C/AL and C


Deadlock Detection

Deadlock Detection

Table locking must be carefully planned and anticipated if a multiuser system is to function correctly.

Automatic Deadlock Detection

If different transactions require write access to several tables at once, you must be careful to avoid a deadlock situation. A deadlock occurs when one transaction locks some of the tables it needs and another transaction has locked some other tables and neither transaction can continue before the other has finished and releases the tables that it has locked.

When this situation, sometimes known as a "Deadly Embrace," occurs, SQL Server chooses one of the participants as the deadlock victim, and informs the unlucky user in an error message.

See Also

Concepts

Data Version
Table Locking
Differences between Commit in C/AL and C


Preventing User-Initiated Deadlock

Preventing User-Initiated Deadlock

The Classic database server has deadlock protection that prevents the system from locking. To prevent individual users from experiencing deadlock, however, certain tables must be locked in a specific order. In the base application, there are four main groups of tables to consider:

  • Journals

  • Non-posted lines and headers

  • Posted lines and headers

  • Ledger entries and registers

Journals

You must lock tables on the lowest level first. A journal has three levels. Templates are on the highest level. Batch names are on the next level. Lines are on the lowest level. When you want to delete a journal template, the application first deletes the journal lines and implicitly locks them. It will then repeat the process with the batch names. You can then delete the template. The rule results in this locking order:

  1. Journal line

  2. Batch name

  3. Journal template

Nonposted Lines and Headers

Because database consistency in the application is very important, there is another rule that must be followed when sales lines are locked before the corresponding sales header. When a user tries to insert a new sales line, the Sales Line table is automatically locked. Another user cannot delete the sales header at the exact same time because the sales lines must be deleted before a sales header can be deleted. Because of this, there will never be sales lines without a corresponding sales header. The same is true for purchase headers and lines. The locking order is as follows:

1. Sales Line table/Purchase Line table

2. Sales Header table/Purchase Header table

Posted Lines and Headers

You must also respect a locking order when working with both posted headers and lines and with headers and lines that are not yet posted. The main principles are that posted headers are locked before posted lines, and purchase tables are locked before sales tables. Posted tables are locked before nonposted tables. These principles result in the following locking order:

1. Purch. Rcpt. Header

2. Purch. Rcpt. Line

3. Sales Shipment Header

4. Sales Shipment Line

5. Sales Invoice Header/Sales Cr. Memo Header/Purch. Inv. Header/ Purch. Cr. Memo Hdr.

6. Sales Invoice Line/Sales Cr. Memo Line/Purch. Inv. Line/ Purch. Cr. Memo Line

7. Purchase Line

8. Purchase Header

9. Sales Line

10. Sales Header

Ledger Entries and Registers

A ledger entry table must always be locked before its corresponding register table. For example, you must lock the G/L Entry table before the G/L Register table.

See Also

Concepts

Read Consistency and Concurrency


Differences between Commit in C/AL and C

Differences between Commit in C/AL and C

Although the concept of committing an update is the same whether you are using

C/AL code or C/FRONT, there are some minor differences. This topic explains these differences in detail.

Note Note

C/FRONT is the toolkit that allows you to develop applications, in the C programming language, while accessing a C/SIDE database.

Commit in C/AL and C

When you want to perform an update using C/FRONT, the first thing you must do is to tell the system explicitly that you want to perform a write transaction (use DBL_BWT, BeginWriteTransaction.) Likewise you must use DBL_EWT (EndWriteTransaction) to explicitly tell the system when your write transaction ends.

When you use C/AL code to update a C/SIDE database, these BeginWriteTransaction and EndWriteTransaction statements are handled implicitly by the system. That is, these commands are executed automatically before and after the C/AL code is executed. This means that if you only need to perform a single write transaction you do not have to commit your update explicitly; it is done automatically. If, however, you need to perform more than one write transaction, you have to use COMMIT()to separate the transactions.

The C/AL code contains two write transactions. When the C/AL code starts to execute, the write transactions are automatically enabled. By issuing the COMMIT() command, you tell the system that the first write transaction has ended, and you prepare the system for the second. As the execution of the C/AL code is completed, the second write transaction ends automatically. When you use C code to perform the same transactions, each transaction must be explicitly encapsulated within the DBL_BWT() and DBL_EWT() commands.

See Also

Concepts

Data Version
Table Locking
Deadlock Detection


Locking in Microsoft Dynamics NAV

Locking in Microsoft Dynamics NAV

This topic explains how locking is used in the two database options for Microsoft Dynamics NAV:

  • Classic Database Server

  • The SQL Server Option

Note Important

The information in the following sections only covers the default transaction type UpdateNoLocks for the SQL Server Option for Microsoft Dynamics NAV. For information about the other transaction types, see C/SIDE Reference Guide.

Both Server Options

Locking

In the beginning of a transaction, the data that you read is not locked. This means that reading data does not conflict with transactions that modify the same data. If you want to ensure that you are reading the latest data from a table, you must lock the table before you read it.

Locking Single Records

Usually, you must not lock a record before you read it even though you may want to modify or delete it afterward. When you try to modify or delete the record, you get an error message if another transaction has modified or deleted the record. You receive this error message because C/SIDE checks the timestamp that it keeps on all the records in a database and detects that the timestamp on the copy you have read is different from the timestamp on the modified record in the database.

Locking Record Sets

Usually, you lock a table before reading a set of records in that table if you want to read these records again to modify or delete them. You must lock the table to ensure that another transaction does not modify these records.

You will not receive an error message if you do not lock the table even though the records have been modified as a result of other transactions being carried out while you were reading them.

Minimizing Deadlocks

To minimize the amount of deadlocks that occur, you must lock records and tables in the same order for all transactions. You can also try to locate areas where you lock more records and tables than you actually need, and then diminish the extent of these locks or remove them completely. This can prevent conflicts from occurring that involve these records and tables.

If this does not prevent deadlocks, you can, lock more records and tables to prevent transactions from running concurrently.

If you cannot prevent the occurrence of deadlocks by programming, you must run the deadlocking transactions separately.

See Also

Concepts

Locking in Classic Database Server
Locking in Microsoft SQL Server
Locking Differences in the Code


Locking in Classic Database Server

Locking in Classic Database Server

Data that is not locked is read from the same snapshot (version) of the database. If you call a modifying function (for example, INSERT, MODIFY, or DELETE), on a table, the whole table is locked.

Locking Record Sets

Usually you lock a table before reading a set of records in that table if you want to read these records again and modify or delete them. With Classic Database Server, you can choose to lock the table with LOCKTABLE(TRUE,TRUE) after reading the records for the first time instead of locking with LOCKTABLE before reading the records for the first time.

When you try to modify or delete the records, you receive an error message if another transaction has modified the records.

You also receive an error message if another transaction has inserted a record into the record set. However, if another transaction has deleted a record from the record set, you will not notice this change. The purpose of locking with LOCKTABLE(TRUE,TRUE) after reading the records for the first time is to improve concurrency by postponing the table lock that Classic Database Server puts on the table.

See Also

Concepts

Locking in Microsoft SQL Server
Locking Differences in the Code


Locking in Microsoft SQL Server

Locking in Microsoft SQL Server

This topic explains how database locking works in Microsoft Dynamics NAV with Microsoft SQL Server.

Locking in SQL Server

When data is read without locking, you get the latest (possibly uncommitted) data from the database. If you call Rec.LOCKTABLE, nothing happens. However, when data is read from the table after LOCKTABLE has been called, the data is locked.

If you call INSERT, MODIFY, or DELETE, the specified record is locked immediately. This means that two transactions, which either insert, modify, or delete separate records in the same table do not conflict. Furthermore, locks are also placed when data is read from the table after the modifying function has been called.

SumIndexFields are maintained when INSERT, MODIFY, or DELETE is called. SQL Server places locks on the records to be updated in the underlying Indexed View. For example, if the application contains a SIFT index on a key consisting of only 'AccountNo' then only one user at the time will be able to modify records on a given AccountNo.

Even though SQL Server initially puts locks on single records, it can also choose to escalate a single record lock to a table lock. This will happen if the overall performance can be improved by not having to set locks on individual records. The improvement in performance must outweigh the loss in concurrency that this excessive locking causes.

If you specify what record to read, for example, by calling Rec.GET, that record is locked. This means that two transactions, which read specific, but separate records in a table does not cause conflicts.

If you browse a record set (read sequentially through a set of records), for example, by calling Rec.FIND('-') or Rec.NEXT, the record set (including the empty space) is locked as you browse through it. This means that two transactions, which just read separate sets of records in a table, will cause a conflict if there are no records between these two record sets. When locks are placed on a record set, other transactions cannot put locks on any record within the set.

Note that C/SIDE determines how many records to retrieve from the server when you ask for the first or the next record within a set. C/SIDE then handles subsequent reads with no additional effort, and fewer calls to the server give better performance. In addition set when you browse.

Microsoft Dynamics NAV with Microsoft SQL Server only supports the default values for the parameters of the LOCKTABLE function – LOCKTABLE(TRUE,FALSE).

See Also

Concepts

Locking in Classic Database Server
Locking Differences in the Code


Locking Differences in the Code

Locking Differences in the Code

A typical use of LOCKTABLE(TRUE,TRUE) in Classic Database Server is shown in the first of the following examples. The equivalent code for the SQL Server Option is shown in the second example. The code that works on both servers is shown in the third example. The RECORDLEVELLOCKING property is used to detect whether record level locking is being used. If this is the case, then you are using the SQL Server Option for Microsoft Dynamics NAV. This is currently the only server that supports record level locking.

Classic Database Server

Example 1

CopyCode image Copy Code
IF Rec.FIND('-') THEN
REPEAT
UNTIL Rec.NEXT = 0;
Rec.LOCKTABLE(TRUE,TRUE);
IF Rec.FIND('-') THEN
REPEAT
Rec.MODIFY;
UNTIL Rec.NEXT = 0;

SQL Server

Example 2

CopyCode image Copy Code
Rec.LOCKTABLE;
IF Rec.FIND('-') THEN
REPEAT
UNTIL Rec.NEXT = 0;
IF Rec.FIND('-') THEN
REPEAT
Rec.MODIFY;
UNTIL Rec.NEXT = 0;

Both Server Types

Example 3

CopyCode image Copy Code
IF Rec.RECORDLEVELLOCKING THEN
Rec.LOCKTABLE;
IF Rec.FIND('-') THEN
REPEAT
UNTIL Rec.NEXT = 0;
IF NOT Rec.RECORDLEVELLOCKING THEN
Rec.LOCKTABLE(TRUE,TRUE);
IF Rec.FIND('-') THEN
REPEAT
Rec.MODIFY;
UNTIL Rec.NEXT = 0;

See Also

Concepts

Locking in Classic Database Server
Locking in Microsoft SQL Server


Working with Multilanguage Functionality

Working with Multilanguage Functionality

Microsoft Dynamics NAV 2009 is multilanguage enabled, which means that you can display the user interface (UI) in different languages.

A multilanguage version of Microsoft Dynamics NAV 2009 is not the same as a localized version.

  • A localized version is a version that is adapted to a local market. All text that is displayed to the user is translated into the local language, and all functional areas are adapted to the requirements of the local market. For example, the Canadian version of Microsoft Dynamics NAV has additional local functionality that applies to the Canadian market.

  • A multilanguage version is a localized version that you can run in different languages, but all local functionality remains the same. For example, you can run the Canadian version of Microsoft Dynamics NAV in both English and French, but it is still the Canadian localized version. It does not contain the same local functionality as the French localized version.

To be able to run a localized version in multiple languages, you must install language modules.

Installing Language Modules

You can install language modules so that you can view text in the user interface in different languages. Once you have installed a language module, you can select that language on the Select Language page in the UI to change the language of all text that is displayed in the UI in captions for text boxes, on command buttons, in menus, and so on.

Note Note

When you change the language of Microsoft Dynamics NAV, you are not changing the language of the data that is stored in Microsoft Dynamics NAV. Changing the text that is stored as application data is not part of the language modules. Examples of such text are the names of items in the inventory or the comments for a customer.

For more information, see Language Modules.

Developing Multilanguage Applications

After you install a language module, you must design your application to take advantage of the multilanguage functionality. For more information, see Developing Multilanguage-Enabled Applications.

Viewing the Application in Different Languages

The language that is displayed to end users in the application depends on several factors, including the language on the localized version of the application, whether a user has specified a global language, whether a developer has specified a global language in C/AL code, or whether a developer has specified a language for a particular object in C/AL code. For more information, see Viewing the Application in Different Languages.


Language Modules

Language Modules

To view Microsoft Dynamics NAV 2009 in multiple languages, you install one or more language modules. The topic describes language modules in Microsoft Dynamics NAV 2009 SP1. For more information about how to install language modules in the original version of Microsoft Dynamics NAV 2009, see Language Modules for Microsoft Dynamics NAV 2009 (requires PartnerSource login).

Language Modules in Microsoft Dynamics NAV 2009 SP1

A language module contains:

  • Translated strings for the user interface (UI) in the Classic client.

  • Translated strings for the UI in the RoleTailored client.

  • Translated strings for the database.

  • Translated strings for Microsoft Dynamics NAV Server, such as for logs and error reporting.

  • Translated strings for the Microsoft Office Outlook Add-in for Microsoft Dynamics NAV.

  • Translated strings for charts on Role Centers in the RoleTailored client.

  • Localized versions of the client Help.

Language modules are binary files that you cannot modify with external tools.

For more information about installing language modules in Microsoft Dynamics NAV 2009 SP1, see How to: Install Language Modules in Microsoft Dynamics NAV 2009 SP1.

If you have customized Microsoft Dynamics NAV 2009, then after you install the appropriate language module, you should also translate the strings for the objects that you added or modified. For more information, see How to: Add Translated Strings By Importing and Exporting Multilanguage Files and How to: Add Translated Strings By Using the Multilanguage Editor.

Language Subdirectory

When you install a language module, a subdirectory for the language is created in the Microsoft Dynamics NAV directory structure. The .stx, .etx, .chm, and .hh files for each language are automatically installed in the subdirectory. The name of the subdirectory is the three-letter language code (Abbreviated Name) that is used by Windows for the particular language. For more information, see Windows Language Virtual Table.


How to: Add Translated Strings By Using the Multilanguage Editor

How to: Add Translated Strings By Using the Multilanguage Editor
See Also

To add string translations for UI elements in a standard country/region-specific version of Microsoft Dynamics NAV 2009, you install a language module so that end users can view the UI elements in a different language. If you have customized objects in the application, then you must also add translations for those objects. You can translate strings in the following ways:

  • By using the Translate tool in the Classic client to import and export multilanguage files that contain translated strings for multiple objects

  • By using the Multilanguage Editor and editing the CaptionML property of individual objects

This topic describes how to use the Multilanguage Editor to edit the CaptionML property of objects. For more information about how to use the Translate tool, see How to: Add Translated Strings By Importing and Exporting Multilanguage Files.

Translating Strings with the Multilanguage Editor

To add a translation in Multilanguage Editor

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, select the object for which you want to add a translation, and then click Design.

  3. In the designer, select the control for which you want to add a translation, click View, and then click Properties.

  4. In the CaptionML property, click the AssistEdit button.

  5. In the Multilanguage Editor, enter the language and the translated text. For more information, see How to: Enter Text in the Multilanguage Editor.

To allow the user to select a specific language from the Tools menu in the application, the following must be true:

  • The application must have the correctly named subfolder.

  • The subfolder must contain the correct fin.stx file.

  • The text strings in the database must be marked with the correct language ID.

  • The license file must contain the correct granule.

See Also

Tasks

How to: Delete Translated Strings

Concepts

Working with Multilanguage Functionality


How to: Add Translated Strings By Importing and Exporting Multilanguage Files

How to: Add Translated Strings By Importing and Exporting Multilanguage Files
See Also

To add string translations for UI elements in a standard country/region-specific version of Microsoft Dynamics NAV 2009, you install a language module so that end users can view the UI elements in a different language. If you have customized objects in the application, then you must also add translations for those objects. You can translate strings in the following ways:

  • By using the Translate tool in the Classic client to import and export multilanguage files that contain translated strings for multiple objects

  • By using the Multilanguage Editor and editing the CaptionML property of individual objects

This topic describes how to use the Translate tool to import and export multilanguage files. For more information about how to use the Multilanguage Editor, see How to: Add Translated Strings By Using the Multilanguage Editor.

Exporting Multilanguage Files

To translate strings for multiple objects, you must first export all text strings.

To export a multilanguage file

  1. In the Classic client, on the Tools menu, point to Translate, and then click Export.

  2. In the Translate Export window, select the location where you want to export the file.

  3. In the File name field, enter an appropriate name for the file.

  4. In the Save as Type field, select the format type, and then click Save.

Translating Multilanguage Files

You can add translated strings directly to the exported file, or you can use a translation tool. If you add translated strings directly to the exported file, then use the following procedure.

To translate strings in a multilanguage file

  1. Open the multilanguage file for editing. For example, open the file with a text editor or in Microsoft Office Excel.

  2. For each string that you want to translate, create a new line in the file.

  3. Copy and paste the source ID of the item to be translated into the new line.

  4. Modify the four-character language code to the language to which you are translating.

  5. Add the translated string to the new line.

    The following illustration uses #### to represent the language code of the language to which you translate the string.

    Translated Strings file in Excel

Importing Multilanguage Files

After you add translated strings to the multilanguage file, you must import the file into the application.

To import a multilanguage file

  1. In the Classic client, on the Tools menu, point to Translate, and then click Import.

  2. In the Translate Import window, navigate to the file that you want to import.

  3. Select the file, and then click Open.

See Also

Concepts

Working with Multilanguage Functionality


How to: Delete Translated Strings

How to: Delete Translated Strings

After you add translated strings into a database, there is only one way to delete them. This procedure describes how to delete translated strings.

To delete a language layer

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, select the object for which you want to delete the translated strings.

  3. On the Tools menu, point to Language Module, and then click Export.

  4. In the Language Module Export window, in the File Name field, enter the path and file name of the file that will contain the deleted strings.

  5. In the Language field, click the AssistEdit button.

  6. In the Windows Language List window, select the language that you want to delete, and then click OK.

  7. In the Language Module Export window, select the Delete language field, and then click OK.

See Also

Tasks

How to: Add Translated Strings By Importing and Exporting Multilanguage Files
How to: Add Translated Strings By Using the Multilanguage Editor
How to: Uninstall Language Modules in Microsoft Dynamics NAV 2009 SP1

Concepts

Working with Multilanguage Functionality


Developing Multilanguage-Enabled Applications

Developing Multilanguage-Enabled Applications

When you are developing in a multilanguage-enabled environment, we recommend that you:

  • Set the application language to English (United States)

  • Specify the Name property in English (United States)

  • Use text constants in your code instead of using hardcoded text strings

  • Verify that everything that is displayed to the user has a Caption property

  • Use the DateFormula data type instead of Text or Code for date formulas

Setting the Application Language

Before you start working in a multilanguage-enabled database, you should set the application language to English (United States). In the Classic client, on the Tools menu, click Languages, and then select English (United States).

Name Property

In Microsoft Dynamics NAV, the code base is in English (United States). This means that the Name Property of objects must always be in English (United States).

The code base in English (United States) includes the following:

  • Object names

  • Field names

  • Function and variable names

  • Comments

  • Option strings

  • Control names

Text Constants

In a multilanguage application, you must use text constants to define strings that you use in your code. A text constant can have multiple values for different languages.

The most common use of text constants is to define the strings that are used as parameters in the following functions:

  • ERROR Function (Dialog)

  • MESSAGE Function (Dialog)

  • CONFIRM Function (Dialog)

  • STRMENU Function (Dialog)

You define text constants in the C/AL Globals or C/AL Locals window. When you enter a string in the ConstValue field, this value is automatically entered as the ConstValueML value for the currently selected language. You can enter a string for other languages by clicking the AssistEdit button in the ConstValue field. This opens the Multilanguage Editor. For more information, see How to: Enter Text in the Multilanguage Editor.

Text constants are automatically assigned unique IDs according to the number ranges listed in Number Ranges for Text Constants. To see the ID for a text constant, open the C/AL Globals or C/AL Locals window where the text constant is defined, and select the text constant. On the View menu, click Properties.

When you are working in the C/AL Editor, if you place the cursor on a text constant, then the value of the text constant in the current application language is shown in the message line in the language that you have selected as the application language.

Caption and CaptionML Properties

Everything that is displayed to the user must have a Caption Property. The Name property is always English (United States), but you use the Caption property to show the name in the user's language. The Caption property copies the value for the current application language from the CaptionML Property.

The CaptionML property allows you to add captions in multiple languages. An example is table 37, field 1, which has the following CaptionML values:

ENU=Document Type; ESM=Tipo documento;FRC=Type de document;ENC=Document Type

These correspond to values for English (United States), Spanish (Mexico), French (Canada), and English (Canada).

If your application language is English (United States), then the value of the Caption property is Document Type. If your application language is Spanish (Mexico), then the value of the Caption field is Tipo documento.

To add captions in different languages, you can either enter values directly in the Value field of the CaptionML property, or you can click the AssistEdit button to open the Multilanguage Editor. For more information, see How to: Enter Text in the Multilanguage Editor.

Note Note

You must click OK to save the information when you exit the Multilanguage Editor window.

Note Note

If you create a new field on a form and you enter a CaptionML value, which is copied to the Caption property, then the value of the Caption property is not shown on the form in Form Designer until you compile, close, and reopen the form. If you enter the caption directly in the Value field of the Caption property, then you do not have to compile, close, and reopen the form to see the Caption property. If you modify the CaptionML property on an existing field in a form, then the new value of the Caption property is shown on the form even in Form Designer.

You can also use the make-ml tool to add captions in different languages. The make-ml tool is part of the Upgrade Toolkit. You can find the toolkit appropriate for your locale on the Product Downloads for Microsoft Dynamics NAV 2009 page (requires PartnerSource log-in).

When you create captions, pay special attention to the following:

  • Option buttons

  • Option strings

  • Option variables

Option Buttons

The value in the OptionValue field is always in English because this value is used by the corresponding global variable and code must always be in English (United States). You must ensure that the value for English (United States) in the CaptionML field is the same as in the OptionValue field.

Option Strings

For option strings, such as a control in a request form, the Name property must remain the number of the control, such as Control 9.

Option Variables

For option variables, such as in a source expression for a FORMAT, STRSUBSTNO, ERROR, MESSAGE, or CONFIRM statement, create a text constant that contains the options, and then use a SELECTSTR statement to select an option from the text constant.

For example, you have the following text constants and variables.

Text constant name | Value
Text000 | Test %1.
Variable name | Data type | Length
NewStr | Text | 30
OptionVar | Option |

OptionVar has an OptionString value of Option1,Option2. In an application that is not multilanguage-enabled, you can have the following code.

CopyCode image Copy Code
NewStr := STRSUBSTNO(Text000, OptionVar);

In a multilanguage-enabled application, the OptionVar values are not translated. Instead of using the Option variable, create the following text constants and variables.

Text constant name | English (US) value | Croatian (Croatia) value
Text000 | Test %1. | Test %1.
Text001 | Option1,Option2 | Opcija1, Opcija2
Variable name | Data type | Length
NewStr | Text | 30
SelStr | Text | 30

To select an option, you use the SELECTSTR function.

CopyCode image Copy Code
SelStr := SELECTSTR(1,Text001);

When you call the STRSUBSTNO function and use the SelStr variable instead of the OptionVar variable, the result string is in the language of the application.

CopyCode image Copy Code
NewStr := STRSUBSTNO(Text000, SelStr);

Date Formulas

In a multilanguage application, if a table contains a date formula field, then you should verify that the field is of the DateFormula Data Type and not the Text Data Type or Code Data Type. A date formula that is stored as a DateFormula data type is converted to a non-language-dependent format.

Similarly, in a multilanguage application, if you use the CALCDATE Function (Date) and if you use a variable for the DateExpression parameter, then you should verify that the variable is of the DateFormula data type so that it is stored in a non-language-dependent format. If you specify a string for the DateExpression parameter, then you should use angle brackets (< >) around the date formula so that date formula is stored in a non-language dependent format. In this way, the calculation will be the same no matter which application language the user has selected.

For example, if a user with the application language set to English (United States) enters a date formula '1W+1D' into a field that is of the DateFormula data type, then to a different user with the application language set to French (France), that field is displayed as '1S+1J'.

See Also

Tasks

How to: View Names and Captions

Concepts

Working with Multilanguage Functionality
Multiple Document Languages


How to: Enter Text in the Multilanguage Editor

How to: Enter Text in the Multilanguage Editor

When you enter captions or text constants for a multilanguage-enabled application, you use the Multilanguage Editor to enter text for multiple languages.

Procedure Title

  1. In the Multilanguage Editor, in the Language field, click the Lookup button.

  2. In the Windows Language List window, select the language that you want to add from the list, and then click OK.

    Note Note

    In the Multilanguage Editor, instead of clicking the AssistEdit button, you can also enter the three-letter code for the language that you want to add and then move the cursor to the Value field. The three-letter code is automatically replaced with the full language description.

  3. In the Multilanguage Editor, in the Value field, enter the text in the language that you entered in the Language field, and then click OK.

  4. (optional) Add a comment by doing the following:

    1. On a blank line in the Multilanguage Editor, in the Language field, click the Lookup button.

    2. In the Windows Language List window, select Comment, and then click OK.

    3. In the Multilanguage Editor, in the Value field of the Comment line, enter your comment.

    Note Note

    A comment is useful to provide help or instructions for a translator.

See Also

Tasks

How to: Add Translated Strings By Using the Multilanguage Editor
How to: Add a Text Constant to a Codeunit


Number Ranges for Text Constants

Number Ranges for Text Constants

C/SIDE assigns unique IDs to text constants according to the table below of number ranges. If you are converting an object with general customer modifications using the conv-ml tool, specify a random number between 1,000,000,000 and 1,000,999,999 as the start number of the number range.

Table

The following table lists the number ranges for text constants.

Developer | From | To
Microsoft Dynamics NAV - base edition | 000 | 9,999
Microsoft Dynamics NAV - Netherlands | 1,000,000 | 1,009,999
Microsoft Dynamics NAV - Belgium | 1,010,000 | 1,019,999
Microsoft Dynamics NAV - USA | 1,020,000 | 1,029,999
Microsoft Dynamics NAV - Canada | 1,030,000 | 1,039,999
Microsoft Dynamics NAV - United Kingdom | 1,040,000 | 1,049,999
Microsoft Dynamics NAV - Iceland | 1,050,000 | 1,059,999
Microsoft Dynamics NAV - Denmark | 1,060,000 | 1,069,999
Microsoft Dynamics NAV - Sweden | 1,070,000 | 1,079,999
Microsoft Dynamics NAV - Norway | 1,080,000 | 1,089,999
Microsoft Dynamics NAV - Finland | 1,090,000 | 1,099,999
Microsoft Dynamics NAV - Spain | 1,100,000 | 1,109,999
Microsoft Dynamics NAV - Portugal | 1,110,000 | 1,119,999
Microsoft Dynamics NAV - France | 1,120,000 | 1,129,999
Microsoft Dynamics NAV - Italy | 1,130,000 | 1,139,999
Microsoft Dynamics NAV - Germany | 1,140,000 | 1,149,999
Microsoft Dynamics NAV - Switzerland | 1,150,000 | 1,159,999
Microsoft Dynamics NAV - Austria | 1,160,000 | 1,169,999
Microsoft Dynamics NAV - Poland | 1,170,000 | 1,179,999
Microsoft Dynamics NAV - Lithuania | 1,180,000 | 1,189,999
Microsoft Dynamics NAV - Latvia | 1,190,000 | 1,199,999
Microsoft Dynamics NAV - Estonia | 1,200,000 | 1,209,999
Microsoft Dynamics NAV - Russia | 1,210,000 | 1,219,999
Microsoft Dynamics NAV - Czech Republic | 1,220,000 | 1,229,999
Microsoft Dynamics NAV - Slovenia | 1,230,000 | 1,239,999
Microsoft Dynamics NAV - Australia | 1,240,000 | 1,249,999
Microsoft Dynamics NAV - New Zealand | 1,250,000 | 1,259,999
Microsoft Dynamics NAV - Singapore | 1,260,000 | 1,269,999
Microsoft Dynamics NAV - South Africa | 1,270,000 | 1,279,999
Microsoft Dynamics NAV - India | 1,280,000 | 1,289,999
Microsoft Dynamics NAV - Argentina | 1,290,000 | 1,299,999
Microsoft Dynamics NAV - Brazil | 1,300,000 | 1,309,999
Microsoft Dynamics NAV - Mexico | 1,310,000 | 1,319,999
Microsoft Dynamics NAV - Croatia | 1,320,000 | 1,329,999
Microsoft Dynamics NAV - North Africa/Middle East | 1,330,000 | 1,339,999
Microsoft Dynamics NAV - Thailand | 1,340,000 | 1,349,999
Microsoft Dynamics NAV - Malaysia | 1,350,000 | 1,359,999
Microsoft Dynamics NAV - Hungary | 1,360,000 | 1,369,999
Microsoft Dynamics NAV - Iceland | 1,370,000 | 1,379,999
General customer modifications | 1,000,000,000 | 1,000,999,999
Add-on | 1,100,000,000 | 1,199,999,999

See Also

Concepts

Working with Multilanguage Functionality


How to: View Names and Captions

How to: View Names and Captions

If you have a multilanguage application, then you need to know how to find the values of both the Name Property of an object, which is in English (United States), and the Caption Property of an object, which is in the local application language.

Viewing Names and Captions in the Development Environment

Each of the following windows displays both the Name property and the Caption property for the items in the list:

  • Object Designer

  • Table List

  • Form List

  • Field List

  • Object List

  • Field Menu

In each window, there is a column with the object number. The following two columns contain the Name property and the Caption property in the current application language, respectively. The following procedure describes how to view a list in Object Designer.

To view the Table List window when creating a page

  1. In Object Designer, click Page, and then click New.

  2. In the New Page window, in the Table field, click the lookup button.

  3. In the Table List window, the first column contains the table number, the second column contains the Name property, and the third column contains the Caption property in the current application language.

In Object Designer and the Field Menu window, you can show or hide columns, including the Caption column.

To show columns in the Object Designer window

  1. In Object Designer, right-click a column header, and then click Show Column.

  2. In the Show Column window, select columns that you want to show, and then click OK.

To hide columns from the Object Designer window

  • In Object Designer, right-click the column header for the column that you want to hide, and then click Hide Column.

In the C/AL Editor, the C/AL scanner displays captions for objects, fields, and text constants. When you place the cursor on an object, field, or text constant, the C/AL scanner displays the Caption property for the object, field, or text constant in the status bar at the bottom of the Classic client window.

In the C/AL Symbol Menu, if you have selected a field name, then the value of the Name property is displayed in the third column, and the value of the Caption property is displayed in the lower-left corner of the window. If you have selected a caption, then the corresponding Name for that caption is displayed in the lower-left corner of the window and the value of the Caption property is displayed in the third column.

Viewing Names and Captions in the Classic client

When you use the Zoom functionality on an object, you can choose to see both the Caption property and the Name property for the fields.

To use Zoom functionality

  1. Open the object, such as a purchase order, and then place the cursor in the relevant field.

  2. On the Tools menu, click Zoom to zoom in.

  3. In the Zoom window, right-click one of the column headers, and then click Show Columns from the list.

  4. In the Show Columns window, select the Field Name field, and then click OK. The Field column shows the Caption values for the current application language, and the Field Name column shows the Name values.

See Also

Concepts

Developing Multilanguage-Enabled Applications


Multiple Document Languages

Multiple Document Languages

With a multlanguage-enabled database you can automatically get the languages needed for multiple document language functionality.

Running Multiple Document Languages

If you have documents that you want to print in the language of the recipient rather than in your own working language, you can add a single line of code in the document to handle this. This functionality is already enabled for most reports in the standard Microsoft Dynamics NAV database. The document is printed in the language that is specified in the Language Code field in the Customer Card window.

In reports that need the multiple document languages functionality, you must insert the following C/AL code as the first line in the OnAfterGet Record() trigger:

CurrReport.LANGUAGE := Language.GetLanguageID("Language Code")

For each of these reports, you must create a new variable, Language, with the data type Record pointing to the Language table (table 8). When you have compiled the object, it will no longer print in the user’s working application language if another language has been specified in the Customer Card window.

See Also

Tasks

How to: Add Translated Strings By Using the Multilanguage Editor
How to: Delete Translated Strings

Concepts

Working with Multilanguage Functionality


Viewing the Application in Different Languages

Viewing the Application in Different Languages

In a multilanguage-enabled application, you can view the text in any language that has been added to the application. For more information about adding languages, see Language Modules.

Changing the Language from the User Interface

You can change the language in which text is displayed from both the Classic client and the RoleTailored client.

When you change the language of the application from the user interface (UI) in either the Classic client or the RoleTailored client, you are changing the global language.

For more information, see How to: Change the Language from the User Interface.

Changing the Language from C/AL Code

You can change the global language from C/AL code, which is the same as changing the language from the UI. To change the global language from C/AL code, use the GLOBALLANGUAGE Function.

You can also set the language of an application object in the Classic client from C/AL code. An object can change its language when it is executed, or it can allow the user to set the language at this point. If you set the language of an object, then that setting overrides the global language setting. To change the language of an object, use the LANGUAGE Function.

Languages and Primary Languages

If a particular string for the current language cannot be found, then Microsoft Dynamics NAV searches for the text in another related language. Languages in Windows are tagged with a primary language ID. For example, the language with ID 1033, which is English (United States), is the primary language for a group of languages that includes ID 2057, which is English (United Kingdom), and ID 3081, which is English (Australia). Similar relationships exist for languages such as French, Spanish, and German.

Microsoft Dynamics NAV uses the primary language if the text for the current language cannot be found. For example, if you are running the German (Switzerland) localized version and you open a form that contains strings that do not exist with the language ID for German (Switzerland), then Microsoft Dynamics NAV looks for a string with the language ID for German (Germany) because German (Germany) is the primary language for German (Switzerland).

The algorithm searches for the text to use in the following order:

  1. The language of the object, which can be specified by a developer in C/AL code.

  2. The primary language of the object language.

  3. The global language that is either selected by the user or specified by a developer in code.

  4. The primary language of the global language.

  5. The language of the localized version of the application.

  6. The primary language of the localized version of the application.

Text is always displayed, but you can have situations in which different pages or even different controls on a page are displayed in different languages.

To view all language IDs and the associated information, such as primary ID, name, and abbreviated name, you can design a page that is based on the Windows Language virtual table. For more information, see Windows Language Virtual Table.

Maintaining SQL Views for Languages

In Microsoft Dynamics NAV with Microsoft SQL Server, in the Classic client, you can specify that SQL Server creates and maintains a view for each language ID that is added to a table or field in Microsoft Dynamics NAV. If you select this option, then external tools can use these views to access the CaptionML property of the object in the required languages instead of using the name that is supplied in the table.

For more information, see How to: Maintain SQL Views for Each Language.

Help in the RoleTailored Client

In the RoleTailored client, Help is always displayed in the same language as Windows even when you select another language in Microsoft Dynamics NAV. To display Help in another language, you must change the region and language settings of Windows.

See Also

Concepts

Working with Multilanguage Functionality


Windows Language Virtual Table

Windows Language Virtual Table

The virtual, read-only Windows Language table displays the languages that Windows supports. You can view its contents by designing a tabular-type form based on the table.

The Table

The Windows Language virtual table contains the following fields.

Field name | Description
Language ID | This field is the primary key. It displays the standard Windows language ID for a specific language. C/AL supports the setting of language using the GLOBALLANGUAGE, WINDOWSLANGUAGE, and object LANGUAGE properties. The values of these properties are taken from this field.
Primary Language ID | Windows languages are grouped. A group consists of a primary language and zero or more secondary languages. The Primary Language ID field contains the Windows Language ID of the primary language.
Name | This field contains the standard Windows name for the language
Abbreviated Name | This field is a secondary key. It contains the standard Windows three-letter code for the language
Enabled | If selected, indicates that the language is globally enabled, form enabled, report enabled, or data port enabled. Your license file determines how a specific language can be used.
Globally Enabled | If selected, indicates that the license file allows you to set the language in question as the global language for the entire application.
Form Enabled | If selected, indicates that the license file allows forms to be shown in a language other than the global language.
Report Enabled | If selected, indicates that the license file allows reports to be printed in a language other than the global language
Dataport Enabled | If selected, indicates that the license file allows data ports to be shown in a language other than the global language.
Primary Code Page | The code page for a language defines the character set available for that language. If you mix text by using multiple code pages, you may not obtain the expected result.
STX File | If selected, indicates that an *.stx file is installed for the language in question. An *.stx file contains general text used in menu labels and system table names.
ETX File | If selected, indicates that an *.etx file is installed for the language in question. An *.etx file contains error messages.
Help File | If selected, indicates that an *.hlp or a *.chm file is installed for the language in question.

See Also

Concepts

Working with Multilanguage Functionality


How to: Maintain SQL Views for Each Language

How to: Maintain SQL Views for Each Language

The Maintain views option determines whether SQL Server creates and maintains a view for each language ID that is added to a table or field in Microsoft Dynamics NAV.

To maintain views for each language

  1. In the Classic client, on the File menu, point to Database, and then click New or Alter.

  2. In the New Database or Alter Database window, on the Integration tab, select Maintain views, and then click OK.

See Also

Concepts

Viewing the Application in Different Languages
Working with Multilanguage Functionality


How to: Change the Language from the User Interface

How to: Change the Language from the User Interface

You can change the language that is used for captions in windows, on command buttons, and in other UI elements from both the Classic client and the RoleTailored client.

To change the language from the Classic client

  1. In the Classic client, on the Tools menu, click Language.

  2. In the Application Languages window, select the language, and then click OK.

To change the language from the RoleTailored client

  1. In the RoleTailored client, click Microsoft Dynamics NAV, and then click Select Language.

  2. In the Select Language page, select the language, and then click OK.

    Note Note

    If you personalize a component such as a FactBox and then select a different language, then the personalized element is displayed in the original language. To view the elements in the new language, restore the default settings and reapply the personalization settings.

See Also

Concepts

Viewing the Application in Different Languages
Working with Multilanguage Functionality


Sorting Numerical Values

Sorting Numerical Values

This topic explains how items, such as documents, are numbered in Microsoft Dynamics NAV. The information is helpful if you use, or are planning to use Microsoft Dynamics NAV with Microsoft SQL Server. This topic is also helpful if you use Classic Database Server and want Microsoft Dynamics NAV to sort numbers correctly when you view data with external programs.

Number Sorting

Code fields in can contain both numerical values and text strings. This ensures that numbers kept in code fields on Classic Database Server are sorted in the correct numerical order. However, this does not necessarily happen when you use external programs to access the same data. External programs may view and sort these numbers as text. This means that when data is sorted, comparisons are made character by character, and not by comparing the numeric content of the strings.

Numbers that you keep in code fields on SQL Server using the Varchar SQL Data Type Property are not sorted in the correct numerical order. Microsoft Dynamics NAV with Microsoft SQL Server sorts the numbers as if they were text strings. The following table illustrates the differences that occur.

Numerical sorting | Text sorting
1 | 1
2 | 10
3 | 100
4 | 2
10 | 3
100 | 4

To avoid this problem, we recommend that you use a numerical series that has a fixed length. You can do this in three ways:

  • Define a numerical series that consists of a predefined number of digits that start with a digit other than zero, for example, 100-399 (300 numbers). If this numerical series is too short for your requirements, you can start a new numerical series, for example, 40,000-69,999 (30,000 numbers). If this numerical series is too short, you can start a new one such as 7,000,000-9,999,999 (3,000,000 numbers). Users will quickly get used to entering numbers that have a fixed length, and the numbers will be sorted correctly.

    1001

    1002

    1003

    …

    9999

    This solution enables you to define the SQL data type as being either Varchar or Integer and the sorting will still be correct.

  • Define a numerical series that consists of a predefined number of digits and that starts with a letter, such as A001-A999. This series will be sorted correctly. When the series is complete, you can define a new series by starting with a different letter. The users will quickly get used to entering numbers that have a fixed length, and the numbers will be sorted correctly.

    A001

    A002

    A003

    …

    A999

  • Define a numerical series that consists of a predefined number of digits that start with zeros, for example, 001-999. We do not recommended this solution because users tend to ignore the zeros and to refer to the first number as 1. Users may, therefore, omit the zeros when entering numbers. Also, the numerical series feature in does not permit numbers to start with zero. Furthermore, Microsoft Dynamics NAV with Microsoft SQL Server will not allow you to save numbers that are defined according to this system as the Integer SQL data type.

Note Important

As a general rule, data types used in fields that are related to each other must be compatible. Therefore, when you use a SQL data type in a field, you will usually have to change the SQL data type settings of related fields in other tables. For example, in the General Ledger application area, if you change the SQL data type of the No. field in the G/L Account table from Varchar to Integer (or if you change the data type from Code to Text), you must change the data type of the G/L Account No. fields in the G/L Entry and G/L Budget Entry tables to the corresponding data type. Failure to do so results in the display of incorrect totals, based on these tables, in the chart of accounts and elsewhere.

Numbering Principles

To ensure that numbers kept in code or text fields are sorted correctly, irrespective of which database server you are using, you must use the following principles:

  • Always use a numerical series that has a fixed length, for example, 100-399.

  • Never use a numerical series such as 1-999 in code or text fields.

  • Never use a numerical series such as 001-999 in code or text fields.

Filters

If you do not follow the numbering principles, problems will arise when you apply filters that involve numbers.

An example of this is if you have not used a numerical series that has a fixed length, when you apply a filter, for example, 10...20, the result will be 10,100...20.

When you follow the numbering principles, you must remember to use these for filters that you apply. Here are two examples:

  • If you do not follow the numbering principles when you apply a filter, for example, 2...10, the result will contain no records. This is because 2, comes after 10.

  • You have followed the numbering principles and are using three-digit numbers. If you forget to follow the same principles when you apply a filter, for example, 10...20, the result will be 100,101,102...199.


CaptionClass Functionality

CaptionClass Functionality

This section describes the CaptionClass functionality and explains how the CaptionClassTranslate function trigger with ID 15 in Codeunit 1 handles this functionality. The topics in this section describe the syntax and the function code of the CaptionClass.

When you set the CaptionClass Property on a field or control, users can configure the caption of a text box that is connected to a label or the caption of a check box without having to modify code. If you set the CaptionClass property on other controls, such as Buttons or Menu Items, the caption will not be displayed.

C/SIDE passes the value of the CaptionClass property to the CaptionClassTranslate function trigger, which has ID 15 on Codeunit 1. This function translates the CaptionClass to a caption that users can see. The following illustration shows this sequence.

sequence to get value of CaptionClass property

Codeunit 1, function trigger ID 15 is called with a language and a CaptionClass. The trigger converts the CaptionClass into the specific caption for that language and returns it as a string. Language is specified as an integer. CaptionClass is a text.

See Also

Concepts

CaptionClass Syntax
CaptionClass Function Code


CaptionClass Syntax

CaptionClass Syntax

This topic describes the syntax of the CaptionClass functionality.

Syntax

If the CaptionClass property of a field or a control is defined, the function trigger CaptionClassTranslate with ID 15 in Codeunit 1 (ApplicationManagement) is called every time the field or control is shown. This function replaces the caption, as defined in the design of the field or control, with another string. The following code example shows the syntax for this procedure.

CaptionClassTranslate (<LANGUAGE>;<CAPTIONEXPR>)

LANGUAGE

<DataType> := [Integer]

<DataValue> := ……

CAPTIONEXPR

<DataType> := [String]

<Length> <= 80

<DataValue> := <CAPTIONAREA>,<CAPTIONREF>

As you can see, two parameters LANGUAGE and CAPTIONEXPR are passed to this function.

LANGUAGE

The LANGUAGE parameter is automatically mentioned as is the Windows Language ID of the active language in Microsoft Dynamics NAV.

For example, if the active language in Microsoft Dynamics NAV is English (United States), LANGUAGE will hold the value 1033.

CAPTIONEXPR

The CAPTIONEXPR parameter holds the content of the CaptionClass property of the field or control. An example is in table 13 Salesperson/Purchaser, the Global Dimension 1 Code (5050) field has the string '1,1,1' as its CaptionClass. Open the Salespeople/Purchasers form, activate the debugger, open the Zoom window, and the CaptionClassTranslate function trigger pops up in the Debugger.

In the C/AL Locals window, you can see that the CAPTIONEXPR parameter holds the string '1,1,1'.

Note Note

In the Zoom window, you will not find the Global Dimension 1 Code field. Instead you find the Department Code field, which is a result of the CaptionClass property and the CaptionClassTranslate function trigger.

Function Code

The function trigger CaptionClassTranslate with ID 15 is similar to a system trigger. A programmer can intervene here every time the CaptionClass property (if it is defined) is evaluated.

The following example shows the trigger in the CRONUS International Ltd. database.

CaptionClassTranslate(Language : Integer;CaptionExpr : Text[80] : Text[1024])

CommaPosition := STRPOS(CaptionExpr,',');

IF (CommaPosition > 0) AND (CommaPosition < 80) THEN BEGIN

CaptionArea := COPYSTR(CaptionExpr,1,CommaPosition - 1);

CaptionRef := COPYSTR(CaptionExpr,CommaPosition + 1);

CASE CaptionArea OF

'1' : EXIT(DimCaptionClassTranslate(Language, CaptionRef));

'2' : EXIT(VATCaptionClassTranslate(Language, CaptionRef));

'3' : EXIT(CaptionRef);

END;

END;

EXIT(CaptionExpr);

This standard code analyzes and unravels the CAPTIONEXPR parameter. This parameter has the following syntax.

CAPTIONEXPR := <CAPTIONAREA>,<CAPTIONREF>

Depending upon the value of the CAPTIONAREA, different procedures are called.

CAPTIONAREA

The first part of the CAPTIONEXPR parameter, to the first comma, is the CAPTIONAREA, and has the following syntax.

CAPTIONAREA

<DataType> := [SubString]

<Length> <= 10

<DataValue> := 1..9999999999

// 1 for Dimension Area

// 2 for VAT

// 3 to return only the CaptionExpr string

CAPTIONREF

The second part of the CAPTIONEXPR parameter, after the first comma, is the CAPTIONREF, and has the following syntax.

CAPTIONREF

<DataType> := [SubString]

<Length> <= 10

<DataValue> :=

IF (<CAPTIONAREA> = 1)

<DIMCAPTIONTYPE>,<DIMCAPTIONREF>

IF (<CAPTIONAREA> = 2)

<VATCAPTIONTYPE>,<VATCAPTIONREF>

Depending upon the value of the CAPTIONAREA, CAPTIONREF can consist of either one (VATCAPTIONTYPE) or two references (VATCAPTIONTYPE,VATCAPTIONREF or DIMCAPTIONTYPE,DIMCAPTIONREF.

Note Note

This is how the standard functionality in Microsoft Dynamics NAV deals with the CaptionClass property. Every field or control with a defined CaptionClass has a string in this property with the syntax described earlier. For new functionality, a programmer could define other syntax and add code to the function trigger CaptionClassTranslate with ID 15 to handle this syntax.

Syntax for CAPTIONREF

As described earlier, the CAPTIONREF part of the CAPTIONEXPR parameter can have the following syntax. If CAPTIONAREA equals 1:

CAPTIONREF := < DIMCAPTIONTYPE >,< DIMCAPTIONREF >

Or if CAPTIONAREA equals 2:

CAPTIONREF := < VATCAPTIONTYPE >,< VATCAPTIONREF >

Dimension Area

If the CAPTIONAREA equals 1, the caption of the field or control should be retrieved from the dimensions information.

DIMCAPTIONTYPE

This reference determines where the main part of the new caption should be retrieved from, as shown in the following syntax.

DIMCAPTIONTYPE

<DataType> := [SubString]

<Length> <= 10

<DataValue> := 1..6

// 1 to retrieve Code Caption of Global Dimension

// 2 to retrieve Code Caption of Shortcut Dimension

// 3 to retrieve Filter Caption of Global Dimension

// 4 to retrieve Filter Caption of Shortcut Dimension

// 5 to retrieve Code Caption of any kind of Dimensions

// 6 to retrieve Filter Caption of any kind of Dimensions

DIMCAPTIONREF

DIMCAPTIONREF consists of a number of sub references:

DIMCAPTIONREF:= < number >,< DIMOPTIONALPARAM1>,

< DIMOPTIONALPARAM2 >

The following syntax describes what < number > can be and what

<DIMOPTIONALPARAM1>, and <DIMOPTIONALPARAM2> are:

DIMCAPTIONREF

<DataType> := [SubString]

<Length> <= 10

<DataValue> :=

IF (<DIMCAPTIONTYPE> = 1)

1..2,<DIMOPTIONALPARAM1>,<DIMOPTIONALPARAM2>

IF (<DIMCAPTIONTYPE> = 2)

1..8,<DIMOPTIONALPARAM1>,<DIMOPTIONALPARAM2>

IF (<DIMCAPTIONTYPE> = 3)

1..2,<DIMOPTIONALPARAM1>,<DIMOPTIONALPARAM2>

IF (<DIMCAPTIONTYPE> = 4)

1..8,<DIMOPTIONALPARAM1>,<DIMOPTIONALPARAM2>

IF (<DIMCAPTIONTYPE> = 5)

[Table]Dimension.[Field]Code, <DIMOPTIONALPARAM1>,

<DIMOPTIONALPARAM2>

IF (<DIMCAPTIONTYPE> = 6)

[Table]Dimension.[Field]Code, <DIMOPTIONALPARAM1>,

<DIMOPTIONALPARAM2>

DIMOPTIONALPARAM1

DIMOPTIONALPARAM1

<DataType> := [SubString]

<Length> <= 30

<DataValue> := [String]

// A string added before the dimension name.

DIMOPTIONALPARAM2

DIMOPTIONALPARAM2

<DataType> := [SubString]

<Length> <= 30

<DataValue> := [String]

// A string added after the dimension name.

VAT

If the CAPTIONAREA equals 2, the caption of the field or control should be replaced by its original caption plus an extra string. This string should state either 'Excl. VAT' or 'Incl. VAT'. The syntax is described below.

VATCAPTIONTYPE

VATCAPTIONTYPE

<DataType> := [SubString]

<Length> := 1

<DataValue> := '0' -> <field caption + 'Excl. VAT'>

'1' -> <field caption + 'Incl. VAT'>

VATCAPTIONREF

VATCAPTIONREF contains the caption of the field or control.

VATCAPTIONREF

<DataType> := [SubString]

<Length> <= 30

<DataValue> := field caption

See Also

Concepts

CaptionClass Function Code


CaptionClass Function Code

CaptionClass Function Code

This topic explains the function code of CaptionClass. For more information about CaptionClass syntax, see CaptionClass Syntax.

DimCaptionClassTranslate (ID 7)

After CaptionClassTranslate has sifted the contents of the CaptionClass property (passed in the CAPTIONEXPR parameter) in a CAPTIONAREA and a CAPTIONREF, DimCaptionClassTranslate will be called (if CAPTIONAREA equals 1). It passes the Language ID and the CAPTIONREF part of the CaptionClass property.

This function can be split into three main parts:

  1. Collect the General Ledger Setup data, if not already collected.

  2. Sift out the comma-separated subparts of the CAPTIONREF (see the previous description of the CAPTIONREF syntax.)

  3. Determine what the caption should be, depending on the DIMCAPTIONTYPE and DIMCAPTIONREF.

CopyCode image Copy Code
DimCaptionClassTranslate(Language : Integer;CaptionExpr : Text[80]) : Text[80]
//Begin (1)
IF NOT GLSetupRead THEN BEGIN
IF NOT GLSetup.GET THEN
EXIT(");
GLSetupRead := TRUE;
//End (1)
END;

// Begin (2)
CommaPosition := STRPOS(CaptionExpr,',');
IF (CommaPosition > 0) THEN BEGIN
  DimCaptionType := COPYSTR(CaptionExpr,1,CommaPosition - 1);
  DimCaptionRef := COPYSTR(CaptionExpr,CommaPosition + 1);
  CommaPosition := STRPOS(DimCaptionRef,',');
IF (CommaPosition > 0) THEN BEGIN
  DimOptionalParam1 := COPYSTR(DimCaptionRef,CommaPosition + 1);
  DimCaptionRef := COPYSTR(DimCaptionRef,1,CommaPosition - 1);
  CommaPosition := STRPOS(DimOptionalParam1,',');
IF (CommaPosition > 0) THEN BEGIN
  DimOptionalParam2 := COPYSTR(DimOptionalParam1,CommaPosition + 1);
  DimOptionalParam1 := COPYSTR(DimOptionalParam1,1,CommaPosition - 1);
END ELSE BEGIN
  DimOptionalParam2 := ";
 END;
END ELSE BEGIN
  DimOptionalParam1 := ";
DimOptionalParam2 := ";
// End (2)
END;

CASE DimCaptionType OF
// Begin (3)
// Code Caption - Global Dimension using No. as Reference.
'1':
BEGIN
 CASE DimCaptionRef OF
 '1':
  BEGIN
   IF Dim.GET(GLSetup."Global Dimension 1 Code") THEN
    EXIT(DimOptionalParam1 + Dim.GetMLCodeCaption(Language) +      DimOptionalParam2)
   ELSE
    EXIT(
     DimOptionalParam1 +
     GLSetup.FIELDCAPTION("Global Dimension 1 Code") +
     DimOptionalParam2);
  END;
 '2':
  BEGIN
   // Same as case '1' for field "Global Dimension 2 Code").
  END;
 END;
END;
 // Code Caption - Shortcut Dimension using No. as Reference.
 '2':
  BEGIN
   CASE DimCaptionRef OF
    '1':
     BEGIN
      IF Dim.GET(GLSetup."Shortcut Dimension 1 Code") THEN
       EXIT(DimOptionalParam1 + Dim.GetMLCodeCaption(Language) +    DimOptionalParam2)
      ELSE
       EXIT(
        DimOptionalParam1 +
        GLSetup.FIELDCAPTION("Shortcut Dimension 1 Code") +
        DimOptionalParam2);
     END;
    '2':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 2 Code".
     END;
    '3':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 3 Code".
     END;
    '4':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 4 Code".
     END;
    '5':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 5 Code".
     END;
    '6':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 6 Code".
     END;
    '7':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 7 Code".
     END;
    '8':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 8 Code".
     END;
    END;
  END;
 // Filter Caption - Global Dimension using No. as Reference.
 '3':
  BEGIN
   CASE DimCaptionRef OF
    '1':
     BEGIN
      IF Dim.GET(GLSetup."Global Dimension 1 Code") THEN
       EXIT(DimOptionalParam1 + Dim.GetMLFilterCaption(Language) + DimOptionalParam2)
      ELSE
       EXIT(
        DimOptionalParam1 +
        GLSetup.FIELDCAPTION("Global Dimension 1 Code") +
        DimOptionalParam2);
     END;
    '2':
     BEGIN
      // Same as case '1' for field "Global Dimension 2 Code").
     END;
   END;
  END;
 // Filter Caption - Shortcut Dimension using No. as Reference.
 '4':
  BEGIN
   CASE DimCaptionRef OF
    '1':
     BEGIN
      IF Dim.GET(GLSetup."Shortcut Dimension 1 Code") THEN
       EXIT(DimOptionalParam1 + Dim.GetMLFilterCaption(Language) + DimOptionalParam2)
      ELSE
       EXIT(
        DimOptionalParam1 +
        GLSetup.FIELDCAPTION("Shortcut Dimension 1 Code") +
        DimOptionalParam2);
     END;
    '2':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 2 Code".
     END;
    '3':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 3 Code".
     END;
    '4':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 4 Code".
     END;
    '5':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 5 Code".
     END;
    '6':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 6 Code".
     END;
    '7':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 7 Code".
     END;
    '8':
     BEGIN
      // Same as case '1' for field "Shortcut Dimension 8 Code".
     END;
  END;
END;
// Code Caption - using Dimension Code as Reference.
'5':
 BEGIN
  IF Dim.GET(DimCaptionRef) THEN
   EXIT(DimOptionalParam1 + Dim.GetMLCodeCaption(Language) + DimOptionalParam2)
  ELSE
   EXIT(DimOptionalParam1);
 END;
'6': // Filter Caption - using Dimension Code as Reference.
 BEGIN
  IF Dim.GET(DimCaptionRef) THEN
   EXIT(DimOptionalParam1 + Dim.GetMLFilterCaption(Language) + DimOptionalParam2)
  ELSE
   EXIT(DimOptionalParam1);
  END;
// End (3)
 END;
END;
EXIT(");

VATCaptionClassTranslate (ID 9)

If CAPTIONAREA equals 2, CaptionClassTranslate passes the CAPTIONEXPR parameter CAPTIONREF, which is actually the VATCAPTIONTYPE, and calls VATCaptionClassTranslate. VATCaptionClassTranslate also passes the Language ID and the CAPTIONREF part of the CaptionClass property. This function can be split into two main parts:

  1. Sift out the comma-separated subparts of the CAPTIONREF.

  2. Determine what the caption should be, depending on the VATCAPTIONTYPE. In either case, the original caption is replaced by its original caption plus the string:

  • 'Excl. VAT' if VATCAPTIONTYPE equals 1.

  • 'Incl. VAT' if VATCAPTIONTYPE equals 2.

CopyCode image Copy Code
VATCaptionClassTranslate(Language : Integer;CaptionExpr : Text[80]) : Text[30]
// Begin (1)
CommaPosition := STRPOS(CaptionExpr,',');
IF (CommaPosition > 0) THEN BEGIN
  VATCaptionType := COPYSTR(CaptionExpr,1,CommaPosition - 1);
// End (1)
VATCaptionRef := COPYSTR(CaptionExpr,CommaPosition + 1);
// Begin (2)
CASE VATCaptionType OF
  '0' : EXIT(COPYSTR(STRSUBSTNO('%1
  %2',VATCaptionRef,Text016),1,30));
  '1' : EXIT(COPYSTR(STRSUBSTNO('%1
  %2',VATCaptionRef,Text017),1,30));
// End (2)
  END;
END;
EXIT(");

See Also

Concepts

CaptionClass Syntax


File Handling

File Handling

The walkthroughs in this section provide step-by-step instructions for handling files in Microsoft Dynamics NAV 2009.

Best Practices

The following are recommended best practices for working with files:

  • Use fully qualified paths to eliminate ambiguity.

  • Be aware of operating system file access restrictions when designing applications that use files. Consider which users have access to files and directories and what access control list (ACL) that you need to apply to file directories.

See Also

Tasks

Walkthrough: Uploading a File from a Client to Microsoft Dynamics NAV Server
Walkthrough: Transferring a File from Microsoft Dynamics NAV Server to the Client


Walkthrough: Uploading a File from a Client to Microsoft Dynamics NAV Server

Walkthrough: Uploading a File from a Client to Microsoft Dynamics NAV Server
See Also
CollapseAll image

This walkthrough demonstrates how to use file functions to send a file from a client to the server, use stream functions to read the file, and use an XMLport to load values into the database. In Microsoft Dynamics NAV 2009, business logic runs on Microsoft Dynamics NAV Server instead of on the client. As a result, any business logic that reads data from a file needs to first move a copy of that file from the client to the server.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating an XML file that contains two elements with values.

  • Creating a table in Microsoft Dynamics NAV to hold the data from the XML file.

  • Creating a codeunit that does the following:

    • Sends the file from a user-specified location to a location on the server

    • Reads the data

    • Writes the data to the table

    • Deletes the file from the server

  • Associating the codeunit with an action on a Role Center page.

  • Testing the codeunit.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license

Expand image Creating an XML File

The first step is to create a simple XML file that contains the data that the codeunit will read into the table. This represents the file on a client computer.

To create the XML file

  1. Open Notepad.

  2. Enter the following code.

    CopyCode image Copy Code
    <?xml version="1.0" encoding="UTF-8"?><head><valueI>10</valueI><valueII>11</valueII></head>

  3. Save the file in the root of the My Documents directory. Name the file simple.xml.

  4. Open the file in Internet Explorer to ensure that the XML is well formed.

Expand image Creating a Table

The next step is to create the table that will hold the data that is read from the XML file.

To create the table

  1. In Object Designer, click Table, and then click New.

    Table Designer opens.

  2. Click Field Name in the first row and then enter IntA. Set Data Type to Integer.

  3. Click Field Name in the second row and then enter IntB. Set Data Type to Integer.

  4. Save the table, giving it a name of TestTable and an ID of 50010.

  5. Close Table Designer.

Expand image Creating the Codeunit

The next step is to create a codeunit that will prompt the user to specify the location of the XML file, load the XML file into a stream, and then write the values of those variables to the table using an XMLport.

To create the codeunit

  1. In Object Designer, click Codeunit, and then click New.

    C/AL Editor opens.

  2. Click the OnRun() function in the C/AL Editor.

  3. Click View and then click C/AL Locals.

    The C/AL Locals window opens.

  4. Click the Variables tab.

  5. Enter the following local variables.

    Name DataType Length

    TestFile

    File

    TestStream

    InStream

    NVOutStream

    OutStream

    ClientFileName

    Text

    1024

  6. Click the next empty line to ensure that the local variables are saved.

  7. Close the C/AL Locals window.

  8. Enter the following code in the C/AL Editor for the OnRun function.

    CopyCode image Copy Code
    BEGIN
    IF ISSERVICETIER THEN BEGIN
        IF UPLOADINTOSTREAM(
                       'Select the simple.xml file',
                        'c:\temp',
                        'XML File *.xml| *.xml',
                         ClientFileName,
                         TestStream)
        THEN MESSAGE('File Successfully Uploaded')
        ELSE
            EXIT;
    END
    ELSE BEGIN
        TestFile.OPEN('C:\temp\simple.xml');
        TestFile.CREATEINSTREAM(TestStream);
    END;
    XMLPORT.IMPORT(50010,TestStream);
    IF NOT ISSERVICETIER THEN TestFile.CLOSE;
END;

  9. Save the codeunit, giving it a name of UploadFile and an ID of 50010.

  10. Close the code editor.

Expand image Creating the XMLport

The next step is to create an XMLport.

To create the XMLport

  1. In Object Designer, click XMLport, and then click New.

    XMLport Designer opens.

  2. Enter the following information.

    Node Name Node Type Source Type Data Source

    head

    Element

    Table

    <TestTable>(TestTable)

    valueI

    Element

    Field

    <TestTable>::IntA

    valueII

    Element

    Field

    <TestTable>::IntB

  3. Set the Indentation property for value I and value II to 1.

  4. Save the XMLport, giving it a name of UploadFile and an ID of 50010.

  5. Close XMLport Designer.

Expand image Associating the Codeunit with an Action

Now that you have the completed codeunit, you need to associate it with an action in the RoleTailored client so it can be tested. In this case, you will add a new action to the Sales Order Processor role center and name it Upload File to Server. When selected, this action will call the codeunit.

To associate the codeunit with an action

  1. In Object Designer, click Page, select page 9006 Order Processor Role Center, and then click Design.

    Page Designer opens.

  2. Click the first empty line on the page, click View, and then click Actions.

    Action Designer opens.

  3. Click the first empty line in Action Designer and in the Caption column for that line, enter Upload File to Server. Set the Type to Action.

  4. With the Upload File to Server line selected, press SHIFT+F4 to open the Properties window.

  5. Set the RunObject property value to c50010. When this action is selected on the role center, codeunit 50010 will run.

  6. Close the Properties window.

  7. Close Action Designer.

  8. Close Page Designer.

Expand image Testing the Codeunit

The final step is to test the codeunit to ensure that it correctly adds the values from the simple.xml file to the TestTable.

To test the codeunit

  1. Open the RoleTailored client.

  2. On the Sales Order Processor role center, click Actions, and then click UploadFileToServer.

    The Select the simple.xml file window opens.

  3. Browse to the location of simple.xml and then click Open.

  4. Click OK.

  5. Open the Classic client.

  6. In Object Designer, click Table, click 50010 Test Table, and then click Run.

    The TestTable-Table window opens with the values of 10 and 11 in the IntA and IntB columns, respectively.

Expand image See Also

Tasks

Walkthrough: Transferring a File from Microsoft Dynamics NAV Server to the Client

Reference

UPLOADINTOSTREAM Function (File)


Walkthrough: Transferring a File from Microsoft Dynamics NAV Server to the Client

Walkthrough: Transferring a File from Microsoft Dynamics NAV Server to the Client
See Also
CollapseAll image

This walkthrough demonstrates how to develop a codeunit that creates a file on Microsoft Dynamics NAV Server, opens the file, writes some data to it, and then downloads that file to a RoleTailored client.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating a codeunit that creates a text file, opens the file, writes some text to the file, and then downloads that file to the client.

  • Associating the codeunit with an action on a Role Center page.

  • Testing the codeunit.

Note Note

The codeunit that you develop is intended for use in the RoleTailored client and does not run in the Classic client.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license

Expand image Creating the Codeunit

The first step is to create the codeunit. In the codeunit, the toFile variable is initially assigned a value of samplefile.txt. If the user specifies another file name, then this new value and the file path are returned in toFile.

To create the codeunit

  1. In Object Designer, click Codeunit and then click New.

    C/AL Editor opens.

  2. Click the OnRun() function in C/AL Editor.

  3. Click View and then click C/AL Locals.

    The OnRun - C/AL Locals window opens.

  4. Click the Variables tab.

  5. Enter the following local variables.

    Name DataType Length

    Name

    Text

    200

    ReturnValue

    Boolean

    TempFile

    File

    ToFile

    Variant

    NewSteam

    InStream

  6. Click the next empty line to ensure that the local variables are saved.

  7. Close the C/AL Locals window.

  8. Enter the following code in the C/AL Editor for the OnRun() method.

    CopyCode image Copy Code
    // ISSERVICETIER checks whether the code is running on the RoleTailored client.
// If so, create a temporary file on NAV server, write the content // to the tempoary file, and then create an instream for the
// temporary file.

IF ISSERVICETIER THEN BEGIN
    TempFile.CREATETEMPFILE();
    TempFile.WRITE('abc');
    TempFile.CREATEINSTREAM(NewStream);
    ToFile:='SampleFile.txt';

    // Tranfer the content from the temporary file on the NAV server to a file on the RoleTailored client.

    ReturnValue:=DOWNLOADFROMSTREAM(
              NewStream,
              'Save File to RoleTailored Client',
              '',
              'Text File *.txt| *.txt',
              ToFile);

    // Close the temporary file and delete it from NAV server.

    TempFile.CLOSE();
END

// If running on the Classic client

ELSE BEGIN
    ToFile:='SampleFile.txt';
    TempFile.CREATE(ToFile);
    TempFile.WRITE('abc');
    ToFile:=TempFile.NAME;
    TempFile.CLOSE();
END;

// Post a message indicating that the file is saved on the client.

MESSAGE(FORMAT(ToFile));

  9. Save the codeunit, giving it a name of FileTransfer and an ID of 50011.

  10. Close the code editor.

Expand image Associating the Codeunit with an Action

Now that you have the completed codeunit, you need to associate it with an action in the RoleTailored client so it can be tested. In this case, you will add a new action to the Sales Order Processor role center and name it File Transfer. When selected, this action will call the codeunit.

To associate the codeunit with an action

  1. In Object Designer, click Page, select page 9006 Order Processor Role Center, and then click Design.

    Page Designer opens.

  2. Click the first empty line on the page, click View, and then click Actions.

    Action Designer opens.

  3. Click the first empty line in Action Designer and in the Caption column for that line, enter File Transfer. Set Type to Action.

  4. With the File Transfer line selected, press SHIFT+F4 to open the Properties window.

  5. Set the RunObject property value to c50011. When this action is selected on the Role Center, codeunit 50011 will run.

  6. Close the Properties window.

  7. Close Action Designer.

  8. Close Page Designer and save the change to page 9006.

Expand image Testing the Codeunit

The final step is to test the codeunit.

To test the codeunit

  1. Open the RoleTailored client.

  2. On the Sales Order Processor role center, click Actions, and then click File Transfer.

    The Export File dialog box appears.

  3. Click Save and save to the default location, noting what that location is.

  4. Click OK.

  5. A message box opens specifying the location of the saved file. Click OK.

  6. Browse to the specified file location on your client computer.

  7. Open the file.

  8. Note that the file contains the text 'abc'.

Expand image See Also

Tasks

Walkthrough: Uploading a File from a Client to Microsoft Dynamics NAV Server


Developing Applications for the Classic Client and RoleTailored Client

Developing Applications for the Classic Client and RoleTailored Client
See Also

If your application must run on both the Classic client and on the RoleTailored client, then you must carefully consider how you will design and develop the application. Additionally, if at design time you do not know if your application may need to run on both clients in the future, then you should design your application so that it can run on both clients.

The following differences in the Classic client and the RoleTailored client can affect application development:

  • Forms and Pages: Forms are used in the Classic client, and pages are used in the RoleTailored client.

  • Reports: From the Classic client, you can view reports in the Classic report layout. From the RoleTailored client, you can view reports in either the Classic report layout or the client report definition (RDLC) report layout.

  • Dataports and XMLports: Dataports are not supported in the RoleTailored client. You use XMLports in the RoleTailored client to import and export data.

  • ISSERVICETIER System Function: You can use the ISSERVICETIER function to execute different code based on the client that you are running.

  • C/AL Behavior: Some C/AL functions behave differently in the Classic client and the RoleTailored client.

  • Using File Data Type Functions: From the Classic client, local files are accessed on the client. From the RoleTailored client, local files are accessed on Microsoft Dynamics NAV Server.

  • Automation Objects: In the Classic client, Automation objects run on the client. In the RoleTailored client, when you create an object, you can specify whether it runs on Microsoft Dynamics NAV Server or on the RoleTailored client.

  • Source Expression Evaluation: Source expressions are evaluated at different times on the Classic client and the RoleTailored client.

  • System Tables: Several System tables are not supported in a three-tier environment.

  • Supported C/AL Data Types, Functions, Properties, and Triggers Some C/AL functions and properties are not supported in the Classic client, and some functions and properties are not supported in the RoleTailored client.

For more information about client architecture in Microsoft Dynamics NAV 2009, see the following topics:

  • RoleTailored Client

  • Tour of the RoleTailored Client for Developers

  • Classic Client

Forms and Pages

In the Classic client, forms are the basis of user interface in the application. In the RoleTailored client, pages are the basis of user interface in the application. You have different options for creating and maintaining forms depending on which clients on which your application must run.

Classic Client Only

If you want your application to run only on the Classic client, then you have the following option for creating and maintaining forms:

  • Create and maintain forms with Form Designer.

RoleTailored Client Only

If you want your application to run on the RoleTailored client only, then you have the following options for creating and maintaining pages:

  • Create and maintain pages with Page Designer.

  • Create forms with Form Designer and then transform the forms to pages with the Form Transformation tool. After the initial form transformation, maintain pages by using Page Designer or by using Form Designer and retransforming your forms to pages.

Both Classic and RoleTailored Clients

If you want your application to run on both the Classic client and the RoleTailored client, then you have the following options for creating forms and pages:

  • Create forms for the Classic client with Form Designer. Create pages for the RoleTailored client with the Form Transformation tool. Maintain forms and pages by using Form Designer to modify forms and then retransforming forms to pages after you make changes.

  • Create forms for the Classic client with Form Designer. Create pages for the RoleTailored client with Page Designer. Maintain forms by using Form Designer and maintain pages by using Page Designer. This approach is not recommended if you have many forms and pages that you must maintain separately with two designers.

Considerations

To decide which tools you want to use to develop pages, consider the following:

  • Do both Form Designer and Page Designer allow you to create the objects that you need for your application?

  • Which designer do you prefer using?

For more information about Form Designer, see Creating and Maintaining Forms. For more information about Page Designer, see Creating and Maintaining Pages. For more information about form transformation, see Transforming Forms to Pages.

Reports

In the RoleTailored client, you can create RDLC report layouts. An RDLC file is a file with an .rdlc extension that is created by Visual Studio Report Designer and stores the layout information for the report. You use both Report Designer in the Classic client and Visual Studio Report Designer to create RDLC report layouts for Microsoft Dynamics NAV 2009. RDLC report layouts provide some new features that are not available in Classic client report layouts. For more information, see Understanding Report Redesign.

If your application runs on both the Classic client and the RoleTailored client, you might want your reports to be exactly the same, regardless of the client. In that case, you can view Classic client report layouts from the RoleTailored client, instead of creating RDLC report layouts. For more information, see How to: View Classic Report Layouts from the RoleTailored Client.

If your application runs on both the Classic client and the RoleTailored client, you can transform your request forms to request pages. The report object contains both the request form and the request page. When your application runs on the Classic client, the request form is used. When your application runs on the RoleTailored client, the request page is used. For more information about transforming request forms, see How to: Transform the Request Form.

To decide which report layouts to use in your application, consider the following:

  • Are any of the features that you want in your reports available in one layout but not in the other? For more information about new features in RDLC reports, see Understanding Report Redesign.

  • Are you familiar with the tools that are required for the report layout that you chose? For Classic report layouts, the tool is the Classic client Report Designer. For RDLC report layouts, the tools are the Classic client Report Designer and Visual Studio Report Designer.

  • If you create RDLC report layouts for existing reports, do you understand the manual updates that are required for the redesigned reports? For more information, see Manual Updates to Redesigned RDLC Report Layouts.

  • Do your reports need to appear exactly the same, regardless of the client?

For more information about designing and maintaining Classic client report layouts, see Designing Reports for the Classic Client. For more information about designing and maintaining RDLC report layouts, see Designing Reports for the RoleTailored Client. For more information about redesigning existing Classic report layouts as RDLC report layouts, see Redesigning Classic Reports with Visual Studio Report Designer.

Dataports and XMLports

If you use dataports to import or export data, your application will run on the Classic client but will result in run-time errors on the RoleTailored client. If your application runs on both the Classic and the RoleTailored clients, we recommend that you use XMLports instead of dataports to import and export data. XMLports are supported on both the Classic and RoleTailored clients. You can configure XMLport objects to achieve the same functionality as dataports in previous versions of Microsoft Dynamics NAV.

When you are developing for the RoleTailored client, you can use additional properties and have access to additional functionality. Request pages and import and export text functionality have been added to XMLports. These properties are visible in the Classic client so that you can access them in XMLport Designer. However, setting or executing an XMLport with these properties in the Classic client has no effect.

Importing and exporting text also works differently in XMLports:

  • XMLports do not have an OnBeforeExportRecord trigger.

  • XMLports support multiple languages for the CaptionML and Language properties.

  • XMLports support UTF-8 and UTF-16 formats for XML.

Note Note

With dataports, you can use the CurrFile object to read and write directly to the input or output file. XMLports do not have a CurrFile object.

For more information about XMLports, see Creating XMLports.

ISSERVICETIER System Function

In some cases, such as if you use automation, access files, or call functions that behave differently or are not supported in the RoleTailored client, you can use the ISSERVICETIER system function. If you call ISSERVICETIER from the Classic client, then the function returns false. If you call ISSERVICETIER from the RoleTailored client, then the function returns true. This allows you to execute different code that is based on the client that you are running. The following sections describe some examples of using ISSERVICETIER.

C/AL Behavior

Some C/AL data types, functions properties, and triggers behave differently when run on the Classic client or when run on the RoleTailored client. You should be familiar with these differences so that when you design code for your application, you can create an application that behaves in the ways that you expect on each client.

The following provides an overview of the behavior differences. For more information, see the specific topic about the data type, function, property, or trigger.

Data type, function, property or trigger Change

BLOB Data Type

In the Classic client, a control on a form can have a SourceExpr that specifies a BLOB field from a table other than the SourceTable for the form. In the RoleTailored client, this is not supported.

Char Data Type

In the Classic client, you can assign a char to any position within the defined length of a text or code variable. In the RoleTailored client, a run-time error occurs if you assign a char to a position that is greater than the current length of the string plus 1.

Code Data Type

In the Classic client, you can assign a char to any position within the defined length of a text or code variable. In the RoleTailored client, a run-time error occurs if you assign a char to a position that is greater than the current length of the string plus 1.

CREATE Function (Automation)

In the RoleTailored client, you can specify if you want the automation object to run on the client or on Microsoft Dynamics NAV Server by using an optional parameter. In the Classic client, the Automation object always runs on the client.

CREATE Function (File)

In the RoleTailored client, if you call CREATE on a file variable that refers to an open file, then the function will not automatically close the existing file and create the new file. You must explicitly call the CLOSE Function (File) to close the existing file. Otherwise, a run-time error occurs.

File Data Type

In the RoleTailored client, if you do not specify the uniform naming convention (UNC) path of a file, then FILE functions access files on the computer running Microsoft Dynamics NAV Server.

In the Classic client, if you do not specify the UNC path of a file, then FILE functions access files on the computer running the client.

For more information, see Using FILE Data Type Functions.

FlowFilters

In the RoleTailored client, it is not supported to have a FlowFilter field as the SourceExpr for a control on a page.

FORM.RUN Function (Form)

If you have code that calls the FORM.RUN function and you run this code on Microsoft Dynamics NAV Server, then the code is translated to call the PAGE.RUN Function instead. For more information, see Using RUN and RUNMODAL Functions.

FORM.RUNMODAL Function (Form)

If you have code that calls the FORM.RUNMODAL function and you run this code on Microsoft Dynamics NAV Server, then the code is translated to call the PAGE.RUNMODAL instead. For more information, see Using RUN and RUNMODAL Functions.

MinOccurs Property

In the Classic client, the minimum number is 0. In the RoleTailored client, if you use Lazy API for XML (LAX), then the minimum number is 1. If you do not use LAX, then the minimum number is 0.

OnInit Trigger

In the RoleTailored client, if you set filters, keys, sort order, or other settings that affect a table view in the OnInit trigger, then the settings are overwritten by the OnOpenForm trigger.

OnValidate (Fields) Trigger

In the RoleTailored client, after a validation error occurs, the user can enter data in other fields.

OPEN Function (File)

In the RoleTailored client, if you call OPEN on a file variable that refers to an open file, then the function will not automatically close the existing file and create the new file. You must explicitly call the CLOSE Function (File) to close the existing file. Otherwise, a run-time error occurs.

PREVIEW Function (Report)

In the Classic client, if you run a report in preview mode and then call CurrReport.PREVIEW, then printing is disabled. In the RoleTailored client, if you run a client report definition (RDLC) report layout in preview mode and then call CurrReport.PREVIEW, then the Print icon is not displayed. If you do not call CurrReport.PREVIEW, then the Print icon is displayed and you can print.

PopulateAllFields Property

In the Classic client, the value of simple identical filters that are set in different filter groups is not assigned to the field when populating a form with a new record.

In the RoleTailored client, the value of simple identical filters that are set in different filter groups is assigned to the field just before executing the OnNewRecord trigger.

Text Data Type

In the Classic client, you can assign a char to any position within the defined length of a text or code variable. In the RoleTailored client, a run-time error occurs if you assign a char to a position that is greater than the current length of the string plus 1.

Variant Data Type

In the Classic client, if an Automation method returns a DateTime in a variant, then the time component is removed when the variant variable is converted to a typed variable. If an Automation method returns a value in a method argument, then the time component is not removed. In the RoleTailored client, the time component is not removed from either a variant return value or a variant method argument when the variant variable is converted to a typed variable.

The following functions are described in detail:

  • Using RUN and RUNMODAL Functions

  • Using FILE Data Type Functions

Using RUN and RUNMODAL Functions

Examples of functions that behave differently when run on the Classic and the RoleTailored clients are FORM.RUN and FORM.RUNMODAL. These functions run a form that you specify. When a form is run modally, no input (keyboard or mouse click) can occur except to objects on the modal form.

The following table shows the result of calling various RUN and RUNMODAL functions from the RoleTailored client and the Classic client.

Client on which code runs | Function call | Result
RoleTailored client | FORM.RUN | Translated to PAGE.RUN. If page exists, it runs; otherwise, a run-time error occurs.
RoleTailored client | FORM.RUNMODAL | Translated to PAGE.RUNMODAL. If page exists, it runs; otherwise, a run-time error occurs.
RoleTailored client | PAGE.RUN | If page exists, it runs; otherwise, a run-time error occurs.
RoleTailored client | PAGE.RUNMODAL | If page exists, it runs; otherwise, a run-time error occurs.
Classic client | FORM.RUN | If form exists, it runs; otherwise, a run-time error occurs.
Classic client | FORM.RUNMODAL | If form exists, it runs; otherwise, a run-time error occurs.
Classic client | PAGE.RUN | Not supported. A run-time error occurs.
Classic client | PAGE.RUNMODAL | Not supported. A run-time error occurs.

If you are developing an application that will run on both the RoleTailored client and the Classic client, then you have the following options for using a RUN or RUNMODAL function to run forms and pages:

  • Use the ISSERVICETIER system function. If you are running on the RoleTailored client, then call PAGE.RUN or PAGE.RUNMODAL. If you are running on the Classic client, then call FORM.RUN or FORM.RUNMODAL. Use this option if the form and the page have different IDs.

  • Always call FORM.RUN or FORM.RUNMODAL and allow the code to be translated automatically to PAGE.RUN or PAGE.RUNMODAL if it is being run on the RoleTailored client. Use this option if you have both a form and a page with the same ID. If you use the form transformation tool to transform the form to a page, then the form and the page have the same ID.

Using FILE Data Type Functions

If you access a file from the RoleTailored client by using a local file name, such as C:\MyFile.txt, then the location that is accessed is on the computer running Microsoft Dynamics NAV Server. If you access a file from the Classic client by using a local file name, such as C:\MyFile.txt, then the location that is accessed is on the client computer. If you are developing an application that will run on both the Classic client and the RoleTailored client, then you can do one of the following:

  • Use the ISSERVICETIER function. If you are running on the RoleTailored client, then either upload the file from the computer running RoleTailored client to the computer running Microsoft Dynamics NAV Server, or download the file from the computer running Microsoft Dynamics NAV Server to the computer running the RoleTailored client.

  • Use the uniform naming convention (UNC) path of the file to specify the computer on which the file resides. If you use the UNC path of the file, then you must ensure that users running the application have the appropriate permissions to access files.

For example, codeunit 419, 3-Tier Automation Mgt., uses the ISSERVICETIER function. If the codeunit is running on the RoleTailored client, then it uploads a file from the computer running the RoleTailored client to the computer running Microsoft Dynamics NAV Server so that it can access the file using other functions.

Note Note

We recommend that when possible, you use the functions in codeunit 419, 3-Tier Automation Mgt., to upload and download files. The functions in this codeunit use the DOWNLOAD Function (File), DOWNLOADFROMSTREAM Function (File), and UPLOADINTOSTREAM Function (File).

For more information about accessing files, see File Handling.

Automation Objects

Before you can use an Automation variable, you must create, or instantiate, the automation server that is referenced by the Automation variable. You use the CREATE Function (Automation) to create the automation server. When you create an automation object from the Classic client, it always runs on the client. On the RoleTailored client, you can choose if the automation object runs on the computer running the RoleTailored client or on the computer running Microsoft Dynamics NAV Server by using an optional parameter in the CREATE function. By default, the automation object runs on the computer running the RoleTailored client. For more information about running automation objects on the RoleTailored client and Microsoft Dynamics NAV Server, see Best Practices for Using Automation With the RoleTailored Client.

Source Expression Evaluation

Source expression evaluation on pages in the RoleTailored client differs from source expression evaluation on forms in the Classic client. On pages, source expressions are evaluated on every call that the client makes to Microsoft Dynamics NAV Server but never between calls. If the value of a source expression is a function of page fields that have been changed, then the source expression is only evaluated and updated the first time that the client calls Microsoft Dynamics NAV Server after the fields were changed. For example, the source expression can be evaluated to perform field validation. There may be an interval when the underlying fields change, but the control that is bound to the source expression displays the old value.

Because source expressions on the RoleTailored client are evaluated on every call that the client makes to Microsoft Dynamics NAV Server, we recommend that you do not create source expressions that are bound to the result of a function that performs multiple tasks, such as writing records to a table.

System Tables

Several tables that you can use when developing for the Classic client are not supported when developing for the RoleTailored client. The following table describes these system tables.

Table name | Table ID
Printer | 2000000039
OCX | 2000000042
Automation | 2000000046
Server | 2000000047
Code Coverage | 2000000049

Supported C/AL Data Types, Functions, Properties, and Triggers

Most C/AL data types, functions, properties, and triggers are supported on both the Classic client and the RoleTailored client. However, some are supported only on the Classic client and some are supported only on the RoleTailored client. For more information about what is supported on which client, see Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client.

See Also

Concepts

Changes in C/AL Behavior and Support from Previous Versions of Microsoft Dynamics NAV
Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client


Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client

Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client
See Also

The following table provides an overview of the C/SIDE data types, functions, properties, and triggers in Microsoft Dynamics NAV 2009 that are supported on either the Classic client or the RoleTailored client. It also includes report properties and functions that are supported on either Classic report layouts or client report definition (RDLC) report layouts.

For more information about the differences, see the specific topic about the data type, function, property, or trigger.

Data type, function, property, or trigger | Change
ACTIVATE Function (Control) | Not supported in the RoleTailored client.
BEEP Function (Dialog) | Not supported in the RoleTailored client.
BottomMargin Property | Not supported on client report definition (RDLC) report layouts. Instead, use the Layout tab of the Report Properties dialog box in Visual Studio Report Designer. For more information, see Report Properties - Layout Tab (Visual Studio Report Designer).
CardFormID Property | Not supported in the Classic client.
ChartPartID Property | Not supported in the Classic client.
CODECOVERAGELOG Function | Not supported in the RoleTailored client.
COMMANDLINE Function | Not supported in the RoleTailored client.
ContainerType Property | Not supported in the Classic client.
CONTEXTURL Function | Not supported in the RoleTailored client.
CREATETEMPFILE Function (File) | Not supported in the RoleTailored client.
CREATETOTALS Function (Report) | Not supported on RDLC report layouts. In most cases, when you create a layout suggestion for a report that uses the CREATETOTALS function, a SUM expression is created instead, and no action is required. For more information, see Built-in Functions for Reports (Visual Studio Report Designer).
Dataport Data Type | Not supported in the RoleTailored client.
DECIMALPLACESMAX Function (Control) | Not supported in the RoleTailored client.
DECIMALPLACESMIN Function (Control) | Not supported in the RoleTailored client.
DeviceFontName Property | Not supported on RDLC report layouts. The device font is controlled by Report Viewer.
EDITABLE Function (Control, Form) | Not supported in the RoleTailored client.
ENABLED Function (Control) | Not supported in the RoleTailored client.
ENVIRON Function | Not supported in the RoleTailored client.
EXPORT Function (BLOB) | Not supported in the RoleTailored client.
ExtendedDataType Property | Not supported in the Classic client.
FreezeColumnID Property | Not supported in the Classic client.
GroupTotalFields Property | Not supported on RDLC report layouts. Instead, you use built-in functions in Visual Studio Report Designer. For more information, see Built-in Functions for Reports (Visual Studio Report Designer).
GroupType Property | Not supported in the Classic client.
HEIGHT Function (Control, Form) | Not supported in the RoleTailored client. The size and position of controls and pages are determined automatically on the display device.
Height Property | Not supported in the RoleTailored client. The size and position of controls and pages are determined automatically on the display device.
HideValue Property | Not supported in the Classic client.
HorzAlign Property | Not supported in the RoleTailored client.
HorzGlue Property | Not supported in the RoleTailored client.
HorzGrid Property | Not supported on RDLC report layouts. Instead, you use the design surface in Visual Studio Report Designer to align items on the layout. For more information, see Defining a Report Layout (Visual Studio Report Designer).
Image Property | Not supported in the Classic client.
IMPORT Function (BLOB) | Not supported in the RoleTailored client.
Importance Property | Not supported in the Classic client.
IndentationColumnName Property | Not supported in the Classic client.
IndentationControls Property | Not supported in the Classic client.
InFooterBar Property | Not supported in the Classic client.
INLINEEDITING Function (Matrix Box,Table Box) | Not supported in the RoleTailored client.
InlineEditing Property | Not supported in the RoleTailored client.
INPUT Function (Dialog) | Not supported in the RoleTailored client.
InstructionalTextML Property | Not supported in the Classic client.
LANGUAGE Function | Not supported in the RoleTailored client.
LeftMargin Property | Not supported on RDLC report layouts. Instead, you use the Layout tab of the Report Properties dialog box in Visual Studio Report Designer. For more information, see Report Properties - Layout Tab (Visual Studio Report Designer).
LOGHEIGHT Function (Form) | Not supported in the RoleTailored client. The size and position of controls and pages are determined automatically on the display device.
LogHeight Property | Not supported in the RoleTailored client. The size and position of controls and pages are determined automatically on the display device.
LOGWIDTH Function (Form) | Not supported in the RoleTailored client. The size and position of controls and pages are determined automatically on the display device.
LogWidth Property | Not supported in the RoleTailored client. The size and position of controls and pages are determined automatically on the display device.
MARK Function (Record) | Not supported in the RoleTailored client.
MARKEDONLY Function (Record) | Not supported in the RoleTailored client.
MaximizedOnOpen Property | Not supported in the RoleTailored client.
MinimizedOnOpen Property | Not supported in the RoleTailored client.
NEWPAGE Function (Report) | Not supported on RDLC report layouts. Instead, use page breaks in Visual Studio Report Designer. For more information, see Defining Page Size and Page Breaks in a Report (Visual Studio Report Designer).
NewPagePerGroup Property | Not supported on RDLC report layouts. Instead, use page breaks in Visual Studio Report Designer. For more information, see Defining Page Size and Page Breaks in a Report (Visual Studio Report Designer).
NewPagePerRecord Property | Not supported on RDLC report layouts. Instead, use page breaks in Visual Studio Report Designer. For more information, see Defining Page Size and Page Breaks in a Report (Visual Studio Report Designer).
NEWPAGEPERRECORD Function (Report) | Not supported on RDLC report layouts. Instead, use page breaks in Visual Studio Report Designer. For more information, see Defining Page Size and Page Breaks in a Report (Visual Studio Report Designer).
NextControl Property | Not supported in the RoleTailored client.
OnAction Trigger | Not supported in the Classic client.
OnHyperlink Trigger | Not supported on RDLC report layouts.
OnPostSection Trigger | Not supported on RDLC report layouts. For more information about how to redesign Classic report layouts that use code on section triggers, see How to: Verify Code on a Report.
OnPreSection Trigger | Not supported on RDLC report layouts. For more information about how to redesign Classic report layouts that use code on section triggers, see How to: Verify Code on a Report.
OBJECTID Function (Form) | Not supported in the RoleTailored client.
OBJECTID Function (Report) | Not supported on RDLC report layouts.
OnCreateHyperlink Trigger | Not supported on RDLC report layouts.
Orientation (Report) Property | Not supported on RDLC report layouts. Instead, you use the Layout tab of the Report Properties dialog box in Visual Studio Report Designer to set the page height and width. For more information, see Report Properties - Layout Tab (Visual Studio Report Designer).
OSVERSION Function | Not supported in the RoleTailored client.
PAGENO Function (Report) | Not supported on RDLC report layouts. Instead, use the PageNumber global variable in Visual Studio Report Designer. For more information, see Global Collections for Expressions in Reports (Visual Studio Report Designer).
PagePartID Property | Not supported in the Classic client.
PageType Property | Not supported in the Classic client.
PaperSize Property | Not supported on RDLC report layouts. Instead, you use the Layout tab of the Report Properties dialog box in Visual Studio Report Designer. For more information, see Report Properties - Layout Tab (Visual Studio Report Designer).
PAPERSOURCE Function (Report) | Not supported on RDLC report layouts. To specify the paper source for an RDLC report layout, use the Page Setup dialog box on the Preview page.
PaperSourceFirstPage Property | Not supported on RDLC report layouts. To specify the paper source for an RDLC report layout, use the Page Setup dialog box on the Preview page.
PaperSourceOtherPages Property | Not supported on RDLC report layouts. To specify the paper source for an RDLC report layout, use the Page Setup dialog box on the Preview page.
PartType Property | Not supported in the Classic client.
Percentage Property | Not supported in the RoleTailored client.
Promoted Property | Not supported in the Classic client.
PromotedCategory Property | Not supported in the Classic client.
PromotedIsBig Property | Not supported in the Classic client.
ProviderID Property | Not supported in the Classic client.
QUERYREPLACE Function (File) | Not supported in the RoleTailored client.
RightMargin Property | Not supported on RDLC report layouts. Instead, you use the Layout tab of the Report Properties dialog box in Visual Studio Report Designer. For more information, see Report Properties - Layout Tab (Visual Studio Report Designer).
SAVEASEXCEL Function (Report) | Not supported on Classic report layouts. You can save a Classic report layout as an .htm or .xml file.
SAVEASHTML Function (Report) | Not supported from Microsoft Dynamics NAV Server. You can save a report as a .pdf file or a Microsoft Office Excel file.
SAVEASPDF Function (Report) | Not supported on Classic report layouts. You can save a Classic report layout as an .htm or .xml file.
SAVEASXML Function (Report) | Not supported from Microsoft Dynamics NAV Server. You can save a report as a .pdf file or a Microsoft Office Excel file.
SHELL Function | Not supported in the RoleTailored client.
ShowAsTree Property | Not supported in the Classic client.
SHOWOUTPUT Function (Report) | Not supported on RDLC report layouts. For more information about conditionally printing report data, see How to: Apply Conditional Visibility Controls.
SystemPartID Property | Not supported in the Classic client.
ToolTip Property | Not supported in the RoleTailored client.
TopMargin Property | Not supported on RDLC report layouts. Instead, you use the Layout tab of the Report Properties dialog box in Visual Studio Report Designer. For more information, see Report Properties - Layout Tab (Visual Studio Report Designer).
TotalFields Property | Not supported on RDLC report layouts. Instead, you use built-in functions in Visual Studio Report Designer. For more information, see Built-in Functions for Reports (Visual Studio Report Designer).
TOTALSCAUSEDBY Function (Report) | Not supported on RDLC report layouts.
UPDATE Function (Form) | Not supported in the RoleTailored client.
UPDATEEDITABLE Function (Control, Form) | Not supported in the RoleTailored client.
UPDATEFONTBOLD Function (Control) | Not supported in the RoleTailored client.
UPDATEFORECOLOR Function (Control) | Not supported in the RoleTailored client.
UPDATEINDENT Function (Text Box) | Not supported in the RoleTailored client.
UPDATESELECTED Function (Control) | Not supported in the RoleTailored client.
URL Function (Report) | Not supported on RDLC report layouts.
VARIABLEACTIVE Function | Not supported in the RoleTailored client.
VertAlign Property | Not supported in the RoleTailored client.
VertGlue Property | Not supported in the RoleTailored client.
VertGrid Property | Not supported on RDLC report layouts. Instead, you use the design surface in Visual Studio Report Designer to align items on the layout. For more information, see Defining a Report Layout (Visual Studio Report Designer).
VISIBLE Function (Control, Form) | Not supported in the RoleTailored client.
WIDTH Function (Control, Form) | Not supported in the RoleTailored client.
Width Property | Not supported in the RoleTailored client.
XPOS Function (Control, Form) | Not supported in the RoleTailored client.
XPos Property | Not supported in the RoleTailored client.
YIELD Function (Dialog) | Not supported in the RoleTailored client.
YPOS Function (Control, Form) | Not supported in the RoleTailored client.
YPos Property | Not supported in the RoleTailored client.

See Also

Concepts

Developing Applications for the Classic Client and RoleTailored Client


Changes in C/AL Behavior and Support from Previous Versions of Microsoft Dynamics NAV

Changes in C/AL Behavior and Support from Previous Versions of Microsoft Dynamics NAV
See Also

The following table provides an overview of the new or changed C/AL data types, functions, properties, and triggers in Microsoft Dynamics NAV 2009. For more information about the changes, see the specific topic about the data type, function, property, or trigger.

Data type, function, property, or trigger | Change
Binary Data Type | Not supported in Microsoft Dynamics NAV 2009.
Code Data Type | In previous versions of Microsoft Dynamics NAV, if you evaluate a Code variable in a CASE statement, then each value set is converted to Code data types. In Microsoft Dynamics NAV 2009, if you evaluate a Code variable in a CASE statement, then the value sets are not converted to Code data types. For more information, see C/AL Conditional Statements.
COMPRESSARRAY Function | Not supported on multidimensional arrays.
COPY Function (Record) | New ShareTable parameter.
Date Data Type | Earliest valid Date changed from January 1, 0000 to January 3, 0001.
DateTime Data Type | Earliest valid DateTime changed from January 1, 0000, 00:00:00.000 to January 3, 0001, 00:00:00.0000000.
Decimal Data Type | The Decimal data type is mapped to the Microsoft .NET Framework common language runtime (CLR) Decimal data type, and the precision and limits are slightly different than the Binary Coded Decimal (BCD) data type in previous versions of C/AL.
ISTEMPORARY Function (RecordRef) | New in Microsoft Dynamics NAV 2009.
NUMBER Function (RecordRef) | If the RecordRef refers to a temporary table, then the NUMBER function returns the ID of the originating physical table and not the run-time generated sequence ID of the temporary table.
READ Function (File) | The Variable parameter must be the maximum length for the type of the variable.
TABLENO Function (RecordID) | If the RecordID refers to a temporary table, then the TABLENO function returns the ID of the originating physical table and not the run-time generated sequence ID of the temporary table.
TEXTMODE Function (File) | If you use the TEXTMODE function on a file that is already open, then an error will occur.
Time Data Type | Precision is in increments of 100 nanoseconds.
Variant Data Type | If an automation method returns a byte string (bstr) in a variant, then you cannot assign that variant directly to a field that is a Code data type. Instead, you must first assign the variant to a code variable and then assign the code variable to the FieldRef value.

See Also

Concepts

Developing Applications for the Classic Client and RoleTailored Client
Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client


Developing Objects

Developing Objects

This section contains topics that describe all of the objects that make up the development environment of Microsoft Dynamics NAV 2009.

Defining the Data Model

To | See
Learn about defining the data model that the application will build on. | Designing Tables

Presenting the Data

To | See
Read about how you create pages and work in Page Designer. | Creating and Maintaining Pages
Read about working with forms using Form Designer. | Creating and Maintaining Forms
Read about creating reports in Report Designer and transforming existing reports. | Designing and Maintaining Reports

Writing Code

To | See
Learn about codeunits, modifying codeunits, adding variables, and functions. | Developing Codeunits
Read more about the C/AL language in Microsoft Dynamics NAV. | Introduction to C/AL
Understand what dataports are used for. | Creating Dataports
Understand what XMLports are used for. | Creating XMLports

Working with Menus

To | See
Learn how to present functionality in menus to the user. | Designing MenuSuites

See Also

Concepts

Development Considerations
Transforming Forms to Pages
Working with Web Services
Improving Application Performance
Creating a More Secure Application


Designing Tables

Designing Tables

Tables are the fundamental objects in any database. They are the objects in which you store and manipulate data. This is true no matter what kind of data you need to manage. When you create a new database, you begin by building the tables. Later, you create forms and reports in order to access and view the data in the tables.

The following sections provide an overview of how to locate Microsoft Dynamics NAV 2009 documentation about designing tables in Microsoft Dynamics NAV.

Creating Tables

This section explains how to design tables to store your data and set up table descriptions that can ease sophisticated data manipulation.

To | See
Learn about the Microsoft Dynamics NAV approach to tables in database design. | Overview of Tables
Design and develop a basic table in Microsoft Dynamics NAV. | How to: Create a Table
Decide which field data type to apply to your data. | Field Data Types and Data Format Considerations
Apply table and field properties and create effective table descriptions. | How to: View or Modify Properties on a Table or Field
Connect table data through primary and secondary keys. | Table Keys
Learn about Microsoft Dynamics NAV features designed to speed up data manipulation and computation. | Table Fields for Instant Access to Data

Using Triggers in Database Design

Microsoft Dynamics NAV supports setting up actions to take place in response to specific events. These are known as triggers. The following topics help to explain how Microsoft Dynamics NAV implements this feature of database design.

To | See
Learn about the set of triggers that Microsoft Dynamics NAV supports for tables and fields. | Table and Field Triggers
Create a table trigger. | How to: Define or Modify Table or Field Triggers
See reference information about specific triggers. | Triggers

Designing Relationships Between Tables

In Microsoft Dynamics NAV, the primary way to establish a connection between tables is to use the TableRelation property. The following topics go into detail about how this works.

To | See
Get a brief introduction to relational database design in Microsoft Dynamics NAV. | Setting Relationships Between Tables
Understand the extra steps SQL Server requires to use the TableRelation property. | Maintaining Table Relationships on SQL Server

Understanding SQL Server and Linked Objects

Microsoft Dynamics NAV supports special handling for SQL Server Object tables. You can find help on linked objects in the following topics.

To | See
Learn about the LinkedObject table property. | Creating Table Defintions from SQL Server Objects (Linked Objects)
Work with other data sources, including Microsoft Excel and Oracle databases. | Accessing Objects in Other Databases or on Linked Servers

See Also

Other Resources

Special C/SIDE Tables


Overview of Tables

Overview of Tables

The records in the C/SIDE database are stored in tables. A C/SIDE table can be visualized as a two-dimensional matrix, consisting of columns and rows. The following illustration shows a table where each row is a record and each column is a field.

A table consists of two parts: the table data and a table description. The table data is the part users often think of as comprising the database, because it contains the actual records with their data fields. The layout and properties of those fields, however, are specified by the table description. The table description is not directly visible to the user. The following illustration shows how the table data and the table description together form a table.

When you design a table, you assign a number of characteristics to it, such as a name, an ID number, and the fields it contains. You also assign a number of characteristics (such as name, ID number, data type, and initial value) to each field. When you design a new table, you also specify which keys you want the system to maintain. All these characteristics are stored in the table description when you save your table design.

The information in the table description is used by the Database Management System (DBMS) and occasionally by database users who need information about the table structure. The table description makes the DBMS flexible, as it lets the system access tables with different structures. The DBMS can extract the definitions of the table structure from the table description and thereby correctly access any table.

The following illustration shows that a table description contains properties, triggers, fields, and keys and shows how these are related.

The table description contains some properties that are related to the table, others that are related to the fields in the table, and other properties related to keys. You can also see that triggers are defined both for the table and for the fields in the table.

See Also

Tasks

How to: Create a Table

Concepts

Table Keys
Table and Field Triggers

Other Resources

Special C/SIDE Tables


How to: Create a Table

How to: Create a Table

When you first create a table, it does not contain any data. Nevertheless, when you create the table you must also decide what types of information you want to store in it. The information is held in fields, and each field can be declared as one of the data types that are available.

To create a table

  1. On the Tools menu, click Object Designer.

    Object Designer opens.

  2. Click Table and then click New.

    Table Designer opens.

In the Table Designer, for each field you add to the table, you enter the field number, name, data type, and optionally, a length and a description.

See Also

Tasks

How to: Add Fields to a Table

Reference

Field Data Types
Table Properties


How to: Add Fields to a Table

How to: Add Fields to a Table

Designing a field means assigning a number of characteristics to it. These characteristics depend on what you intend to use the field for. After you have added fields to a table in Table Designer, you must save the table before you can add any records. After you have saved a table, it appears in the list of tables in Object Designer.

All the tables and fields that you create have two forms of identification:

  • A unique identification number (integer). When you access your database using either C/SIDE or C/FRONT, this number uniquely identifies all the tables and fields.

  • A name (an alphanumeric string) that serves as a label (such as CUSTOMER or CITY).

This name appears when you run the table and should be meaningful and easily understood. This name is secondary information and can be changed at any time.

To add a field to a table

  1. On the Tools menu, click Object Designer.

    Object Designer opens.

  2. Click Table and then click New.

    Table Designer opens.

  3. In the first empty row, enter a Field Name and a Field No. Enter a Data type and appropriate Length. Description is optional.

See Also

Reference

Field Properties
Field Data Types


How to: Save a New Table

How to: Save a New Table

When you design the fields and keys for a new table, you need to save the table in the database before you can use it. After you have saved a table, it appears in the list of tables shown in Object Designer.

To save a table

  1. With the focus on Table Designer, on the File menu, click Save.

    The Save As dialog box opens.

  2. In the ID field, enter a number that will serve as a unique table identification.

    Note Note

    There are restrictions about which numbers you can use. Contact your Microsoft Certified Partner for information.

  3. In the Name field, enter the name of the table.

  4. Clear the Compiled check box if you do not want the table to be compiled when it is saved.

See Also

Tasks

How to: Create a Table


Field Data Types

Field Data Types

After you select an identification number and name for a field, you have to select an appropriate data type. You can use many different types of fields in the C/SIDE database system. Each type is designed to hold a specific kind of information, such as text, numbers, dates, and so on.

Fields in a record can be of the following types.

Data type Description Size

BigInteger Data Type

A 64-bit integer.

8 bytes

Binary Data Type

Contains binary data. The binary data is stored in the record. The size of the corresponding SQL data type, VARBINARY, is the number of bytes in the field’s value. (A)(B)

Maximum length is 250 bytes

BLOB Data Type

Binary Large Object. Used to store bitmaps and memos. Notice that the BLOB is not stored in the record, but in the BLOB area of the table.

The size of the corresponding SQL data type, IMAGE, is the number of bytes in the field’s value. (A)(B)

8 bytes in the record + size of BLOB data (maximum 2 GB)

Boolean Data Type

Assumes the values TRUE or FALSE. When formatted, a Boolean field is shown as "Yes" or "No". The size of the corresponding SQL data type, TINYINT, is 1 byte. (A)(B)

4 bytes

Code Data Type

An alphanumeric string, which is right-justified if the contents are numbers only. If letters or blanks occur among the numbers, the contents are left-aligned. All letters are converted to uppercase upon entry.

The field must be defined to be between 1 and 250 characters. The space used by a code field equals the maximum length of the text plus two bytes. The first of the extra bytes holds information about the length of the string, and the second byte stores alignment information.

In the SQL Server Option for Microsoft Dynamics NAV, code fields work in a different way. You can use the SQL Data Type property to indicate whether code fields can contain integers or text strings.

For information about the SQL Data Type property, see SQL Data Type Property. For more information about the sorting of numeric values in code fields, see Sorting Numerical Values.

The size of the corresponding SQL data type, VARCHAR, is 1 byte per character in the field’s value. (A)(B)

Maximum string length + 2 bytes

Date Data Type

A date value in the range from January 1, 0 to December 31, 9999. An undefined date is expressed as 0. All dates have a corresponding closing date. The system regards the closing date for a given date as a period that follows the given date but comes before the next normal date; that is, a closing date is sorted immediately after the corresponding normal date but before the next normal date.

The size of the corresponding SQL data type, DATETIME, is 8 bytes. (A)(B)

4 bytes

DateFormula Data Type

Used to verify the date entered by the user. The syntax is for example:

CopyCode image Copy Code
30D (=30 days)
CM+1M (=current month plus one month)
D15 (=on the 15th of each month)

4 bytes

DateTime Data Type

Represents a point in time as a combined date and time. The datetime is stored in the database as Coordinated Universal Time (UTC) and is always displayed as local time in Microsoft Dynamics NAV.

Local time is determined by the time zone regional settings used by your computer.

You must always enter datetimes as local time. When you enter a datetime as local time, it is converted to UTC using the current settings for the time zone and daylight saving time.

The DateTime data type does not support closing dates.

Stored as two 4 byte integers

Decimal Data Type

A decimal number between -10^63 and 10^63. The exponent ranges from -63 to 63. Decimal numbers are held in memory with 18 significant digits. The representation of a decimal number is a Binary Coded Decimal (BCD). The size of the corresponding SQL data type, DECIMAL(38,20), is 17 bytes. We recommend that you construct decimals that operate on numbers within the range of +/- 999,999,999,999,999.99. You can construct larger numbers in some cases, but overflow, truncation or loss of precision can occur.

(A)(B)

12 bytes

Duration Data Type

Represents the difference between two points in time, in milliseconds. This value can be negative.

8 bytes

GUID Data Type

Globally unique identifier (GUID).

16 bytes

Integer Data Type

Denotes an integer between -2,147,483,647 and 2,147,483,647. The size of the corresponding SQL data type, INTEGER, is 4 bytes. (A)(B)

4 bytes

Option Data Type

An option field is defined with an option string, which is a comma-separated list of strings representing each valid value of the field. This string is used when a field of type Option is formatted and its value is converted into a string.

For example, the Option field "Color" is defined with the option string "Red,Green,Blue". Valid values of the field are then 0, 1, and 2, with 0 representing "Red" and so on. When the "Color" field is formatted, 0 is converted into the string "Red", 1 into "Green", and 2 into "Blue".

The size of the corresponding SQL data type, INTEGER, is 4 bytes. (A)(B)

4 bytes

RecordID Data Type

Unique record identifier.

TableFilter Data Type

This data type is used to apply a filter to another table.

Currently, this can only be used to apply security filters from the Permission table.

Text Data Type

Any alphanumeric string. The field must be defined to be between 1 and 250 characters. The space used by a text field equals the maximum length of the text plus one byte. This extra byte is a used to hold the length of the string. An empty text string has the length zero.

The size of the corresponding SQL data type, VARCHAR, is 1 byte per character in the field’s value. (A)(B)

Maximum string length + 1 byte

Time Data Type

Any time in the range 00:00:00 to 23:59:59.999. A time field contains 1 plus the number of milliseconds since 00:00:00 o'clock, or 0 (zero), an undefined time. A time value is calculated in the following way:

CopyCode image Copy Code
Time = 1 + (number of milliseconds since 00:00:00).

The size of the corresponding SQL data type, DATETIME, is 8 bytes. (A)(B)

A time field is stored as an integer (four bytes)

(A) The calculation of the size of a specific SQL Server record requires more than simply summing the sizes of the field values. Refer to Microsoft SQL Server documentation for further information.

(B) This is the SQL Server data type that Microsoft Dynamics NAV uses when it creates the Microsoft Dynamics NAV data type. For more information, see Identifiers, Data Types and Data Formats in the SQL Server Option for Microsoft Dynamics NAV.

Note Note

In Classic Database Server, data is stored with a four byte alignment for performance reasons. The sizes of text, code, and binary fields (that can have variable lengths) are rounded up to the nearest value that is a multiple of four. For example, a 10-character text string occupies 12 bytes.

In addition to the fields discussed in this section, the C/SIDE database system also includes the following special types of fields that are used to retrieve data:

  • FlowField

  • FlowFilter

For more information, see FlowFields Overview and FlowFilter Overview.

Expand image See Also

Concepts

C/AL Functions


Identifiers, Data Types and Data Formats in the SQL Server Option for Microsoft Dynamics NAV

Identifiers, Data Types and Data Formats in the SQL Server Option for Microsoft Dynamics NAV
See Also

This topic describes the identifiers, data types, and data formats that are used in the SQL Server Option.

Naming Identifiers

Identifiers for SQL Server tables and columns are based upon the table names and field names for the corresponding tables and fields of a Microsoft Dynamics NAV table definition. If you set a table’s DataPerCompany property to Yes, the SQL Server table name is prefixed by the company name. The two names are separated by the ($) symbol. For example, the SQL Server table name for the Customer table of the CRONUS International Ltd. company is CRONUS International Ltd_$Customer. If the DataPerCompany property of a table is set to No, there is no prefix.

The primary key of a Microsoft Dynamics NAV table is created in a SQL Server table as a primary key constraint. The name of the primary key is based on the table name with a suffix of $0, for example, CRONUS International Ltd_$Customer$0. Any secondary keys in a Microsoft Dynamics NAV table that must be created and maintained in SQL Server, that is, the MaintainSQLIndex key property is set to Yes, will have SQL Server indexes created that are named after an internal key ID with a $ prefix. Examples of this are $1 and $4.

If the database maintains SQL views for language IDs, the system creates a SQL view by prefixing the SQL Server table name with the Windows language ID. For example, if you want to refer to the Customer table in the CRONUS International Ltd. company in German (standard), the SQL view is DEU$CRONUS International Ltd_$Customer. For more information about multilanguage functionality, see Working with Multilanguage Functionality.

If the database maintains relationships, Microsoft Dynamics NAV creates foreign key constraints using the SQL Server table name and TableRelation property information. The names of the constraints have the following format:

  • <table name>$FK$T<referencing table ID>_F<referencing field ID>$T<referenced table ID>.

Here is an example using the Customer table:

  • CRONUS International Ltd_$Customer$FK$T18_F107$T308.

When you create a Microsoft Dynamics NAV table with keys that contain SumIndexFields, indexed views are created to hold the precalculated sums. These views are named based on the company, table name, and key number. For example [CRONUS International Ltd_$G_L Entry$VSIFT$8].

Representation of Data Types

Every available Microsoft Dynamics NAV data type is mapped to an appropriate SQL Server data type in the tables of the SQL Server Option for Microsoft Dynamics NAV. The following table shows which SQL Server data type is used for the corresponding Microsoft Dynamics NAV data type.

Microsoft Dynamics NAV data type | SQL Server data type
Integer | INTEGER
Option | INTEGER
Code(n) | VARCHAR(n) INTEGER SQL_VARIANT
Text(n) | VARCHAR(n)
Decimal | DECIMAL(38,20)
Date | DATETIME
Time | DATETIME
DateTime | DATETIME
Boolean | TINYINT
Binary(n) | VARBINARY(n)
BLOB | IMAGE
DateFormula | VARCHAR(32)
TableFilter | VARBINARY(252)
BigInteger | BIGINT
Duration | BIGINT
GUID | UNIQUEIDENTIFIER
RecordID | VARBINARY(n)

Each of the SQL Server data types is created as NOT NULL except the IMAGE type, which allows NULL.

Compatibility of Data Types

Some of the SQL Server data types are compatible with other Microsoft Dynamics NAV data types. The following table shows the extended compatibility of SQL Server data types with Microsoft Dynamics NAV data types.

SQL Server data type | Microsoft Dynamics NAV data type
CHAR (n) | Code(n) Text(n) DateFormula
NCHAR (n) | Text(n)
NVARCHAR (n) | Text(n)
INTEGER | Code
TINYINT | Integer Option
SMALLINT | Integer Option
NUMERIC(p,s), MONEY, SMALLMONEY, REAL, FLOAT(n), DECIMAL | Decimal Integer Option Boolean
SMALLDATETIME | Date
BIT | Integer Option Boolean
BINARY (n) | Binary(n)
TEXT | BLOB
NTEXT | BLOB
UNIQUEIDENTIFIER | Binary(16) Text(36)

See Also

Reference

Field Data Types

Concepts

Developing Multilanguage-Enabled Applications


Data Format Considerations

Data Format Considerations

In the SQL Server Option for Microsoft Dynamics NAV, data formats impact the way your data is compared and sorted

Code Fields

In the SQL Server Option for Microsoft Dynamics NAV, code fields can be represented by several SQL Server data types. Code fields have a property, SQL Data Type, which determines whether they contain integers, text strings, or a mixture of both.

To set code field properties

  1. On the Tools, click Object Designer.

  2. Click Table and select the appropriate table.

  3. Click Design.

  4. Select the field whose data type is defined as code, click View, and then click Properties.

You can set the SQL Data Type property to Varchar, Integer, or Variant. Leaving the value as Undefined is the same as selecting Varchar, which is the default value.

When you create a table in the SQL Server Option for Microsoft Dynamics NAV, the code field data is stored in VARCHAR, INTEGER, or SQL_VARIANT columns in the SQL Server table that correspond to the SQL Data Type property’s values Varchar, Integer, or Variant.

Varchar

When you set the value of the SQL Data Type property of a code field to Varchar, all the values in the field are compared and sorted as character data, including numeric values.

Integer

When you set the value of the SQL Data Type property of a code field to Integer:

  • All the values in the field are compared and sorted as integers. No alphanumeric values can be stored in the field.

  • If you enter negative values in the column outside Microsoft Dynamics NAV using external tools, they cannot be read into Microsoft Dynamics NAV.

  • The value "0" (zero) is used to represent an empty string in Microsoft Dynamics NAV.

  • Nonnumeric code values or any numeric values beginning with "0" (zero) cannot be entered in the code field.

Variant

When you set the value of the SQL Data Type property of a code field to Variant:

  • The values in the field are compared and sorted according to their base data type. Numeric values are sorted after alphanumeric values.

  • Data that is entered into the code field in Microsoft Dynamics NAV is stored as either the VARCHAR or INTEGER base data type, depending on the value that has been entered.

  • Any value beginning with "0" (zero) can be entered in the code field and is stored as an INTEGER base data type.

Note Note

Be aware that the Variant data type is not supported by all the third-party tools that can be used to access data in SQL Server databases.

Data and Time Fields

SQL Server stores information about both date and time in columns of the DATETIME and SMALLDATETIME types. For date fields, Microsoft Dynamics NAV uses only the date part and places a constant value for the time. For a normal date, this contains 00:00:00:000. For a closing date, it contains 23:59:59:000 for a DATETIME and 23:59:00:000 for a SMALLDATETIME.

The Microsoft Dynamics NAV undefined date is represented by the earliest valid date in SQL Server: 01-01-1753 00:00:00:000 for a DATETIME, and 01-01-1900 00:00:00:000 for a SMALLDATETIME.

For time fields, only a SQL Server DATETIME type can be used. Microsoft Dynamics NAV uses only the time and places a constant value for the date: 01-01-1754. The Microsoft Dynamics NAV undefined time is represented by the same value as an undefined date.

In order for Microsoft Dynamics NAV to interpret date and time values correctly, the formats mentioned earlier must be used when linking Microsoft Dynamics NAV table definitions to external tables or views. For more information, see Using Linked Objects.

To reformat a DATETIME or SMALLDATETIME column that is to be used as a date field in Microsoft Dynamics NAV, an UPDATE statement can be applied to the table data. The following is an example of such an update statement.

CopyCode image Copy Code
UPDATE [My Table] SET [My Date] = CONVERT(CHAR(10), [My Date], 120)

For a closing date, a CONVERT style of 120 can be used to set the appropriate time part. To reformat a time field, a similar statement can be used.

CopyCode image Copy Code
UPDATE [My Table] SET [My Time] = CAST('1754-01-01 '+CONVERT(CHAR(8), [My Time], 108) AS DATETIME)

As an alternative to modifying the table data, you can create a view that applies the necessary conversion to the column and gives the column an alias. However, you cannot update views that are created in this way and it is more efficient to change the data than to apply conversions for every row.

Note Note

The information about date and time fields only applies to fields of the Date data type and Time data type; it does not apply to fields of the DateTime data type.

See Also

Reference

Field Data Types

Concepts

Identifiers, Data Types and Data Formats in the SQL Server Option for Microsoft Dynamics NAV


Accessing Microsoft Dynamics NAV Tables with External Tools

Accessing Microsoft Dynamics NAV Tables with External Tools

You can access data in Microsoft Dynamics NAV tables with external tools, such as Microsoft Enterprise Manager. When you do this, the values in fields that contain the code, date, and time data types with a specific format, must be manipulated correctly for data modification or comparison. When you use external tools, no special processing of code field data is required to join fields in different tables, if you use the same SQL data type value for each code field in a join or CAST the value to the appropriate data type.

In the New Database and Alter Database windows, you can choose to maintain SQL views. If you enable this option, SQL Server will create and maintain a view for each language ID that is added to a table in Microsoft Dynamics NAV. The system creates a SQL view by prefixing the SQL Server table name with the Windows language ID for each CaptionML value.

This means that external tools can use a view of the object in the user’s language, for example, Spanish, rather than the object name. The object name could be in another language, for example, English (United States).

The view is updated by every change in the CaptionML values of a table. For more information, see Working with Multilanguage Functionality.

See Also

Concepts

Developing Multilanguage-Enabled Applications
Identifiers, Data Types and Data Formats in the SQL Server Option for Microsoft Dynamics NAV


How to: View or Modify Properties on a Table or Field

How to: View or Modify Properties on a Table or Field

Use the following procedure to view or modify properties for a table or a field.

To view or modify table or field properties

  1. On the Tools menu, click Object Designer.

    Object Designer appears.

  2. Click Table to view the list of tables.

  3. Select a table and then click Design.

    The table opens in Table Designer.

  4. To modify table properties, place the cursor on an empty line in Table Designer. Press F3 to create an empty line if one does not exist.

    -or-

    To modify field properties, place the cursor on the field in the table.

  5. Click View and then click Properties.

    The Properties window appears.

  6. To modify a property value, enter the new value in the Properties window. After entering the new value, update the property by pressing ENTER or by clicking outside of the property.

See Also

Reference

Table Properties
Field Properties


Table Properties

Table Properties

A table in C/SIDE has a number of properties that determine the behavior of the table. When you create a table, C/SIDE automatically defines a number of default values for these properties. Depending on what the table is going to be used for and how it is related to other application objects, you may want to change these default values. C/SIDE contains the following table properties.

Property name | Use
ID Property | Sets a unique identifier for the table.
Name Property | Defines the table name, which is used as the table caption.
Caption Property | Displays the table caption in the currently selected language. This value is taken from the CaptionML Property, if a value is set.
CaptionML Property | Provides the text that is used to identify a control or other object in the user interface. This property is multilanguage enabled and can contain a list of text in different languages. The text that is actually used is selected according to the current language setting of the user.
Description Property | Include an optional description of the table. This description is for internal purposes only and is not visible to the end user. A short description of the table’s purpose makes it easier to maintain the application.
DataPerCompany Property | Determines whether data in this table is available to all companies or only the current company. Yes if data is available only to this company; otherwise, No. The default value is Yes.
Permissions Property | Defines extended permissions for the table.
LookupFormID Property | Defines the ID of the form you want to use as a lookup.
DrillDownFormID Property | Defines the ID of the form you want to use as a drill down.
DataCaptionFields Property | Defines a list of fields to be used as captions when a record from this table is displayed in a form or a page.
PasteIsValid Property | Use this property to enable inserting records into this table using the paste command. Yes if you want to allow insert by pasting; otherwise, No. The default is Yes.
LinkedObject Property | Use this property to link to SQL Server objects. Yes to link the table to an existing SQL Server object.
LinkedInTransaction Property | Determines whether the table can read and modify data from linked data sources, such as Microsoft Office Excel, Access, or another SQL server. This property is only visible when the value of the LinkedObject Property is set to Yes. For more information, see Creating Table Defintions from SQL Server Objects (Linked Objects).

Expand image See Also

Reference

Field Properties


Field Properties

Field Properties

Just like tables, all the fields in C/SIDE have a number of properties that determine their behavior. When you create a field, C/SIDE automatically suggests a number of default values for these properties. Depending on the purpose of the field, you will sometimes want to change these default values.

C/SIDE contains the following field properties. The first table list the properties that are common to most field types.

Property name | Description
Field No. Property | Assigns a unique numeric ID to this field.
Name Property | Specifies the name of the field.
Caption Property | Specifies the text used to identify a control based on the field.
CaptionML Property | Specifies the text that is used to identify a control or other object in the user interface. The CaptionML property is multilanguage enabled and can contain a list of text in different languages. The text that is used is selected according to the current language setting of the user.
CaptionClass Property | Controls the caption that is used in the label of a field in a database table or in the label of a control on a form.
Description Property | Includes an optional description of the field. This description is for internal purposes only and is not visible to the end user.
Data Type Property | Specifies the data type of a table field.
Enabled Property | Determines whether the field is enabled.

A field may have additional properties, depending on its data type. The following table lists properties that apply to various field types.

Property Name | Description
DataLength Property | Specifies the maximum length of the data stored in a code or text field.
InitValue Property | Defines an initial value for a field.
FieldClass Property | Define the class for a field. That is, specifies whether it is a normal field, a FlowField, or a FlowFilter field.
CalcFormula Property | Defines a formula used by a FlowField.
AltSearchField Property | Defines an alternative search field.
DecimalPlaces Property | Sets the number of decimal places shown to the user. This property also performs validation of whether user input conforms to this setting.
Editable Property | Determines whether a field can be edited.
NotBlank Property | Forces the user to make a non-blank entry in this field.
BlankNumbers Property | Determines whether a range of numbers will be set to blank as they are formatted.
Numeric Property | Forces the user to enter numbers in this field.
CharAllowed Property | Sets the characters you will allow the user to enter in this field.
DateFormula Property | Validates the syntax of a date expression entered by the user.
Standard day/time unit Property | Specifies the unit of measure that is used when you enter data into Duration fields.
MinValue Property | Sets the minimum value for the contents of a field.
MaxValue Property | Sets the maximum value for the contents of a field.
Title Property | Adds a title to a field. The first letter in each word is capitalized.
ValuesAllowed Property | Specifies the values you want to allow in the field. Can be specified either as a range or as distinct values, or as a combination of these.
AutoIncrement Property | Specifies whether each field value is automatically given a new number that is greater than the number given to the previous value.
TableRelation Property | Defines relationships to other tables. For more information, see Setting Relationships Between Tables.
ValidateTableRelation Property | Indicates whether a table relationship is validated.
TestTableRelation Property | Indicates whether the field is included in table relationship tests.
TableIDExpr Property | Specifies the ID of the table to which you want to apply a table filter.
BlankZero Property | Determines whether the fields appears blank if the value is 0 (zero) or FALSE.
DataLength Property | Defines the length of a data field.
OptionString Property | Defines an option string (a comma-separated string of options). The maximum size is 1000 characters.
ClosingDates Property | Determines whether closing dates are allowed.
AutoFormatType Property | Determines how data is formatted.
AutoFormatExpr Property | Determines how data is formatted.
SignDisplacement Property | Shifts negative values to the right for display purposes.
SQL Data Type Property | Specifies the data type you want to allow in a code field. This property applies to code fields in the SQL Server Option for Microsoft Dynamics NAV.
ClearOnLookup Property | Specifies whether the current contents of the field are deleted before the value the user selects via the lookup is added.
SubType Property | Defines the subtype of a BLOB field, for example a Bitmap or a Memo.
Compressed Property | Specifies whether a BLOB is compressed. This property only applies to BLOB fields and only on the SQL Server Option.
OptionCaption Property | Defines the text string options that are displayed to the user.
OptionCaptionML Property | Sets the strings that are displayed to the user for selecting an option. The OptionCaptionML property is only used if the field has an OptionString property. The OptionString property contains the set of values that are acceptable choices, and it is one of these values that will be saved in the database or used in C/AL code.

Expand image See Also

Reference

Table Properties


How to: View and Sort Table Data

How to: View and Sort Table Data

Usually, you use a form to view the data in a table, but you can also view the data directly by running the table from Object Designer.

To view table data without using a form

  1. Open Object Designer and select the table to view.

  2. Click Run.

    The table data is displayed in a tabular format.

Changing Table Sort Order

Table data is displayed in the sort order defined by the current key. If more than one key is defined for the table, you can switch between keys to change the sort order.

To view table data with a different sort order

  1. Open Object Designer and select the table to view.

  2. Click Run.

  3. From the View menu, click Sort.

    The Object - Sort window appears.

  4. Under Key, click the key that defines the sort order that you want to use.

  5. Under Order, click Ascending or Descending to control the record display order.

  6. Click OK or Apply to apply the new key.

    If you click OK, the Sort dialog box closes. If you click Apply, the Sort dialog box remains open. Using Apply is convenient if you frequently change the sort order.

See Also

Tasks

How to: Add Records to a Table


How to: Add Records to a Table

How to: Add Records to a Table

Data is usually entered in a table by using a form, but you can also enter it directly.

To add records to a table without using a form

  1. Open Object Designer and select the table to view.

  2. Click Design.

    The table data is displayed in a tabular format.

  3. Place the cursor in an empty line or press F3 to create an empty line.

  4. Enter data in the fields and then press ENTER.

  5. When you have finished entering data, close the table.

    Note Note

    You do not have to save the table. Records are automatically saved and updated when you leave a field after entering a value in it.

See Also

Tasks

How to: View and Sort Table Data


Changing the Design of Tables that Contain Data

Changing the Design of Tables that Contain Data

When you design the tables in your database, you determine which fields they contain. But you will often need to modify the design of some of the tables after they have been in use for a while. Typically you will want to add or delete fields, or make changes to field names or data types.

Rules for Changing Tables

You can modify tables that do not contain data at any time. However, when the table contains data, a number of restrictions apply. The following table lists some general rules.

Modification | Rule
Change a field name | You can always change the name of a field.
Change a field number | You can always change the number of a field. This causes Microsoft Dynamics NAV to run through all the application objects in order to update all the references to this field. This can be a time consuming process.
Change a field data type | You can change the data type for a field only if there is no data in this field for any of the records in the table. There is one exception to this rule—you can change the data type of a field from Code to Text even if the field contains data for some records.
Add a field to a table | You can always add a field to a table.
Delete a field | To delete a field, you must delete all data from the field in all records in the table. You must also remove all references to the field from other tables, forms, and reports.
Change the length of a String field | You can always increase the length of a String field. Whether you can decrease the length of a String field depends on the contents of all the values in the column in the table. The minimum length of a String field is determined by the longest string in the column.

See Also

Tasks

How to: Add Fields to a Table
How to: View or Modify Properties on a Table or Field


Table Keys

Table Keys

The database management system (DBMS) keeps track of each field with the field number and the record's primary key. The primary key is composed of up to 20 fields in a record. The combination of values in fields in the primary key makes it possible for the DBMS to perform a unique identification of each record. The primary key determines the logical order in which records are stored, regardless of their physical placement on disk.

Logically, records are stored sequentially in ascending order and are sorted by the primary key. Before adding a new record to a table, the DBMS checks that the information in the record's primary key fields is unique and only then inserts the record into the correct logical position. Records are sorted "on the fly," so the database is always structurally correct. This allows for fast data manipulation and retrieval.

A table description contains a list of keys. A key is a sequence of one or more field IDs from the table. Up to 40 keys can be associated to a table. The first key in the list is the primary key.

The primary key is always active, and the DBMS keeps the table sorted in primary key order and rejects records with duplicate values in primary key fields. Therefore, the values in the primary key must always be unique. Note that it is not the value in each field in the primary key that must be unique, but it is the combination of values in all fields that make up the primary key.

The C/SIDE database system does not support tables that do not have any keys.

Primary and Secondary Keys

You cannot exceed 20 fields in the primary key together with all the fields in secondary keys and all SumIndexFields. For example, if you have no SumIndexFields and your primary key includes four distinct fields, then your secondary keys can include these four fields and up to 16 other fields. If you have no SumIndexFields and your primary key consists of 20 distinct fields, then your secondary keys must consist only of combinations of these fields.

Note Note

When you run Microsoft Dynamics NAV 2009 with Microsoft SQL Server and you have more than 16 fields in the key, then the key must be unique within the first 16 fields. If the key is not unique within the first 16 fields, then you will get the following error message when importing an object during an upgrade:

The CREATE UNIQUE INDEX statement terminated because a duplicate key was found for the object name [object] and the index name [index].

Secondary Keys

A secondary key uses an additional structure that is called an index. This is similar to the idea of an index that is used in textbooks. A textbook index alphabetically lists important terms at the end of a book. Next to each term are page numbers. You can quickly search the index to find a list of page numbers (addresses), and you can locate the term by searching the specified pages. The index is an exact indicator that shows where each term occurs in the textbook.

When you define a secondary key and mark it as active, an index is automatically maintained and reflects the sorting order that is defined by the key. Several secondary keys can be active at the same time.

A secondary key can be changed into an inactive key, which does not occupy database space, and the DBMS does not use time during updates to maintain its index. Inactive keys can be reactivated, although this can be time consuming because the DBMS must scan the entire table to rebuild the index.

The fields that make up the secondary keys do not always contain unique data, and the DBMS does not reject records with duplicate data in secondary key fields. If two or more records contain identical information in the secondary key, then the DBMS uses the primary key for the table to resolve this conflict.

Sort Orders and Secondary Keys

The following example shows how the primary key influences the sort order when a secondary key has been activated. The Customer table includes four entries (records), and the records in the Customer table have two fields: Customer Number and Customer Name.

The following is the key list for the Customer table.

Key | Key type | Definition
1 | Primary | Customer Number
2 | Secondary | Customer Name

When you sort by the primary key, the Customer table looks like the following table.

Customer Number | Customer Name
001 | Customer C
002 | Customer A
003 | Customer B
004 | Customer C

If you select the secondary key for sorting, then the order is based on the contents of the Customer Name field. Because the contents of these fields are not unique, the records must be subsorted according to the primary key.

Customer Name | Customer Number
Customer A | 002
Customer B | 003
Customer C | 001
Customer C | 004

Note that the two records that have the same Customer Name value are sorted by Customer Number.

How Keys Affect Performance

Searching for specific data is easier if several keys have been defined and maintained for the table that holds the desired data. The indexes for each key provide specific views that enable quick, flexible searches. There are advantages and disadvantages to using many keys, as demonstrated in the following table.

If you | Performance improves when you | Performance slows when you
Increase the number of secondary keys that are marked as active. | Retrieve data in several different sorting sequences because the data is already sorted. | Enter data because indexes for each secondary key must be maintained.
Decide to use only a few keys. | Enter data because a minimal number of indexes are maintained. | Retrieve data. You may need to define or reactivate the secondary keys to get the appropriate sorting. Depending on the size of the database, this can take some time, because the index must be rebuilt.

The decision whether to use a few or many keys is not easy. The choice of appropriate keys and the number of active keys to use should be the best compromise between maximizing the speed of data retrieval and maximizing the speed of data updates (operations that insert, delete, or modify data). In general, it may be worthwhile to deactivate complex keys if they are rarely used.

The overall speed depends on the following factors:

  • Size of your database.

  • Number of active keys.

  • Complexity of the keys.

  • Number of records in your tables.

  • Speed of your computer and its hard disk.

See Also

Tasks

How to: Define Primary and Secondary Keys

Concepts

Keys, Queries, and Performance


How to: Define Primary and Secondary Keys

How to: Define Primary and Secondary Keys

A maximum of 20 distinct fields can be used to define a primary key. The number of fields used in the primary key limits the number of fields in the secondary keys. Fields used by one key can also be used in another key; however, no more than 20 unique fields can be used to create primary or secondary keys.

This means that if your primary key includes four distinct fields, your secondary keys can include these four fields, and at most 16 other fields. Correspondingly, if your primary key consists of 20 distinct fields, then your secondary keys must consist only of combinations of these fields.

When you create a table in Table Designer, by default C/SIDE uses the field with the lowest field number as the primary key. Use the following procedure to define a different primary key.

To define a primary key

  1. On the Tools menu, click Object Designer.

  2. Click Table.

  3. Select a table from the list and then click Design.

  4. Select the first empty line and then from the View menu, click Keys.

    The Keys window appears.

  5. In the first line of the Keys window, enter the primary key as a comma-delimited list; for example, "ID Number, Name".

Defining Secondary Keys

Up to 40 keys can be defined for a table. The first key defined is the primary key. All the other keys are secondary keys and are optional. Secondary keys are used to view records in an order that is different from the order defined by the primary key fields.

To define a secondary key

  1. On the Tools menu, click Object Designer.

  2. Click Table.

  3. Select a table from the list and then click Design.

  4. Select the first empty line and then from the View menu, click Keys.

    The Keys window appears.

  5. The first line shows the primary key. Enter the secondary keys on the following lines as comma-separated lists; for example: Name, Address.

See Also

Tasks

How to: View or Modify Properties on a Key

Concepts

Table Keys


Key Properties

Key Properties

The keys associated with a table have properties that describe their behavior, just as tables and fields do. When you create a key, C/SIDE automatically suggests a number of default values for these properties. Depending on the purpose of the key, you will sometimes want to change these default values.

C/SIDE contains the following properties for keys.

Property Name | Use
Enabled Property | Determines whether the system will maintain an index for the key. You cannot use a key unless it is enabled.
Key Property | Defines the key.
SumIndexFields Property | Determines the fields for which the system will maintain a SumIndex.
KeyGroups Property | Determines which key groups the key is a member of. By making the key a member of a predefined key group you can have the key defined and only enable it when it is going to be used.
BackupKey Property | Checks if any errors occurred the last time you restored a backup.
MaintainSQLIndex Property | Determines whether a SQL Server index corresponding to the Microsoft Dynamics NAV key should be created.
MaintainSIFTIndex Property | Determines whether SIFT structures should be created in SQL Server to support the corresponding SumIndexFields for the Microsoft Dynamics NAV key.

See Also

Tasks

How to: View or Modify Properties on a Key


How to: View or Modify Properties on a Key

How to: View or Modify Properties on a Key

Use the following procedure to view or modify properties for a table or a field.

To view or modify key properties

  1. On the Tools menu, click Object Designer.

    Object Designer appears.

  2. Click Table to view the list of tables.

  3. Select a table and then click Design.

    The table opens in Table Designer.

  4. Click View and then click Keys.

    The Keys window opens.

  5. Place the cursor on the line defining the key for which you want to view or modify properties.

  6. Click View and then click Properties.

    The Properties window appears.

    To modify a property value, enter the new value in the Properties window. After entering the new value, update the property by pressing ENTER or clicking outside of the property.

See Also

Concepts

Key Properties


Table Fields for Instant Access to Data

Table Fields for Instant Access to Data

In addition to conventional data fields, which hold values, Microsoft Dynamics NAV provides three kinds of specialized fields for speedy data retrieval. These fields help to improve performance:

  • SumIndexFields

  • FlowFields

  • FlowFilter

In This Section

SumIndexFields Overview

FlowFields Overview

FlowFilter Overview

See Also

Reference

Field Data Types

Concepts

SumIndexFields


SumIndexFields Overview

SumIndexFields Overview

A SumIndexField is a decimal field that can be attached to a key definition. This is the fundamental feature of the Microsoft Dynamics NAV database that forms the basis for FlowFields. SumIndexFields permit fast calculation of sums of numeric columns in tables, even in tables with thousands of records. This occurs because SumIndexFields are maintained when the database record is updated.

Advantages of SumIndexFields

SumIndexFields enable the speedy calculation of sums of columns. The resulting totals are displayed in FlowFields.

For example, assume you want the sum of all the values in the Amount field. In a conventional database system, the DBMS is forced to access every record and add each value in the Amount field. This is a time-consuming operation in a database with thousands of records. With Microsoft Dynamics NAV, it can take as little as two accesses (if the best key is used) to sum the Amount for these records.

This special index structure, a SumIndexField, is associated with a key. Each key can have up to 20 SumIndexFields.

During database design, a decimal field can be associated with a key as a SumIndexField. This tells the DBMS to create and maintain a structure that contains the accumulated sum of values in a column. When a new current key is selected, any SumIndexFields associated with it become accessible.

See Also

Concepts

FlowFields Overview

Other Resources

Table Fields for Instant Access to Data


FlowFields Overview

FlowFields Overview

FlowFields are a powerful feature of the C/SIDE database system, and strongly influence the way C/SIDE applications are designed. FlowFields and the underlying concept of SumIndexFields increase performance in activities such as calculating the balance of your customers. In traditional database systems, this involves a series of accesses and calculations before a result is available. With FlowFields, the result is immediately available.

FlowFields are not a permanent part of the table data. A FlowField can be thought of as a virtual field, which is an extension to the table data. Because the information in FlowFields exists only at run time, values in FlowFields are automatically initialized to 0 (zero). To update a FlowField, use the C/AL function <Record>.CALCFIELDS. If a FlowField is the direct source expression of a control on a form, the FlowField will automatically be calculated when the form is displayed.

FlowField Types

There are seven types of FlowFields. Each is described in the following table.

FlowField type | Field type | Description
Sum | decimal | The sum of a specified set within a column in a table.
Average | decimal | The average value of a specified set within a column in a table.
Exist | Boolean | Indicates whether any records exist within a specified set in a table.
Count | integer | The number of records within a specified set in a table.
Min | any | The minimum value in a column within a specified set in a table.
Max | any | The maximum value in a column within a specified set in a table.
Lookup | any | Looks up a value in a column in another table.

Example

Consider the Customer table in the following illustration. This table contains two FlowFields. The field named Any Entries is a FlowField of the Exist type, and the Balance field is a FlowField of the Sum type.

The figure shows that the value in the Balance FlowField for customer number 10000 (Windy City Solutions) is retrieved from the Amount column in the Customer Entry table. The value is the sum of the amount fields for the entries that have the customer number 10000.

CopyCode image Copy Code
Sum = 10 + 20 + 30 = 60.

The values shown in the Balance column in the Customer table for customers 10010, 10020, and 10040 are found in the same way. For customer number 10030 the value is 0 (zero), as there are no entries in the Customer Entry table that have a Customer No. that equals 10030.

In this example, the Balance FlowField in the Customer table reflects the sum of a specific subset of the Amount fields in the Customer Entry table. How the calculation of a FlowField is to be made, is defined in a calculation formula. The calculation formula for the Balance field is:

CopyCode image Copy Code
Sum("Customer Entries".Amount WHERE(CustNo=FIELD(CustNo)))

Correspondingly, the Any Entries field, which indicates whether any entries exist, has the following definition:

CopyCode image Copy Code
Exist("Customer Entries" WHERE(CustNo=FIELD(CustNo)))

See Also

Tasks

How to: Create a FlowField

Concepts

SumIndexFields Overview

Other Resources

Table Fields for Instant Access to Data


How to: Create a FlowField

How to: Create a FlowField

The following procedure describes how to set up a FlowField.

To create a FlowField

  1. On the Tools menu, click Object Designer. Open the table that you want to add a FlowField to in the Table Designer.

  2. Select the line for the field that you want to define as a FlowField, such as the Amount field.

  3. On the View menu, click Properties. The Properties window of the Amount field displays.

  4. In the FieldClass property field, select FlowField from the drop-down list.

  5. In the CalcFormula property field, enter the calculation formula for the FlowField.

    For more information, see Calculation Formulas and the CalcFormula Property.

  6. (optional) In the Editable field, select No.

See Also

Tasks

How to: Create, View, and Edit a Calculation Formula


Calculation Formulas and the CalcFormula Property

Calculation Formulas and the CalcFormula Property

A FlowField is always associated with a calculation formula that determines how the FlowField is calculated. The following syntax is valid for the CalcFormula property.

CopyCode image Copy Code
<CalculationFormula> ::=
    [-]Exist(<TableNo> [WHERE (<TableFilters>)]) |
    Count(<TableNo> [WHERE (<TableFilters>)]) |
    [-]Sum(<TableNo>.<FieldNo> [WHERE(<TableFilters>)])|
    [-]Average(<TableNo>.<FieldNo> [WHERE (<TableFilters>)]) |
    Min(<TableNo>.<FieldNo> [WHERE (<TableFilters>)]) |
    Max(<TableNo>.<FieldNo> [WHERE (<TableFilters>)]) |
    Lookup(<TableNo>.<FieldNo> [WHERE (<TableFilters>)])
<TableFilters> ::=
    [<TableFilter> {,<TableFilter>}]
<TableFilter> ::=
    <DstFieldNo>=CONST(<FieldConst>) |
    <DstFieldNo>=FILTER(<Filter>) |
    <DstFieldNo>=FIELD(<SrcFieldNo>) |
    <DstFieldNo>=FIELD(UPPERLIMIT(<SrcFieldNo>)) |
    <DstFieldNo>=FIELD(FILTER(<SrcFieldNo>)) |
    <DstFieldNo>=FIELD(UPPERLIMIT(FILTER(<SrcFieldNo>)))

Parts of the formula are described in the following table.

Symbol | Description
<TableNo> | Specifies the table holding the information to be used in the FlowField.
<FieldNo> | Specifies the column from which you want to compute values.
<TableFilters> | A list of filters to be used in the computation of the FlowField.
<TableFilter> | A table filter can be one of the following: a constant expression, a filter expression, a value from ordinary fields, or a FlowFilter field. A key for the other table must exist and include the fields used in the filters.
<DstFieldNo> | Specifies the destination field number.
<SrcFieldNo> | Specifies the source field number.
<Filter> | A filter expression such as 10|20..30.

See Also

Tasks

How to: Create, View, and Edit a Calculation Formula

Concepts

FlowFields Overview
FlowFilter Overview


How to: Create, View, and Edit a Calculation Formula

How to: Create, View, and Edit a Calculation Formula

The following procedure describes the steps to take to create and revise a calculation formula.

To create, view, and edit a calculation formula

  1. On the Tools menu, click Object Designer. Open the table to which you want to add a calculation formula.

  2. Select the field for which you want to create, view, or edit the calculation formula.

  3. Click View, and then click Properties to open the Properties window.

  4. Find the CalcFormula property.

  5. Enter the calculation formula directly or click the AssistEdit button. When you click the AssistEdit button, the following dialog box is displayed.

  6. Click the drop-down button to select the appropriate calculation method. Click the Reverse Sign option to reverse the sign of the result (only for Sum and Average). Use the lookup buttons to select the table and column (field) from which to get the information. If necessary, you can add a table filter to specify a limited set of records. Click the AssistEdit button to the right of the Table Filter field and C/SIDE opens the Table Filter window.

  7. On each line in this window, you can define a field filter. For each field filter, specify a field, a type, and a value. You can also set the OnlyMaxLimit and the ValueIsFilter options.

The following example illustrates where the information in the Table Filter window comes from. The Balance at Date field in the G/L Account table is a decimal type FlowField. This field is calculated from values in the Amount Column in the G/L Entry table.

Some of the fields in the G/L Account table are FlowFilter fields. By entering filter expressions into these fields, the user can affect the calculation of FlowFields (such as Balance at Date) at run time. The user can enter filter values in a FlowFilter form.

If the user enters a date filter expression in the Date Filter field, it is transferred via the table filter and used in the Date column in the G/L Entry table.

You can use the OnlyMaxLimit option to remove the lower limit from a range defined by a filter expression. For example, if the filter expression is defined as a range x..y, setting the OnlyMaxLimit option transforms the expression into ..y.

The ValueIsFilter option determines how the system interprets the contents of the field referred to in the Value column in the Table Filter window. For example, if the field contains the value 1000..2000, setting the ValueIsFilter option will cause this value to be interpreted as a filter rather than as a specific value.

See Also

Concepts

FlowFields Overview
FlowFilter Overview


FlowFilter Overview

FlowFilter Overview

A user may want to limit calculations to include only those values in a column that have some specific properties. For example, a user may want to sum only the amounts of customer entries that are entered in April. This is possible if the application has been designed using FlowFilter fields in connection with the FlowFields.

The following illustration shows the relationship between various types of database fields and the calculation formula.

The filters defined in the calculation formula can consist of constants, values from ordinary fields, and filters given as parameters in FlowFilter fields. In FlowFilter fields, a user can enter a filter value (via the user interface in a C/SIDE application) that will affect the calculation of a FlowField.

See Also

Concepts

FlowFields Overview


Dividing the Database into Companies

Dividing the Database into Companies

The DBMS can access only one logical database at a time, but this database can be divided into one or more companies. A company is a "subdatabase," and its primary use is to separate and group data in the same database. Fields and tables are identified by a number, but companies are identified by a name. A company bundles one or more data tables together into a logical superstructure that is identified by the company name. Other than the shared company name, the different tables within a company have nothing in common.

Opening a company is your first step after opening the database or connecting to a server.

The following illustration shows a database with four tables.

The four table descriptions on the left apply to each of the data tables, which are logically sorted into three companies. The records in the tables, G/L Account, Customer, and Vendor have the same structure and the same field definitions, even though they belong logically in three different companies. Only the data stored in the fields differ. The information in a Table Description can be used by tables from more than one company, no redundant information will be stored. This minimizes the size of the database.

Even though you have selected a specific company, you can still access data in any table in any other company. Use the CHANGECOMPANY Function (Record) to explicitly define which other company you want to access.

More than one application can access the same company and the same tables at the same time. For more information about how the DBMS controls these multiple accesses, see Table Locking.

See Also

Tasks

How to: Create and Delete a Table Description


How to: Define or Modify Table or Field Triggers

How to: Define or Modify Table or Field Triggers

The following procedure describes how to set up a trigger.

To define or modify a table or field trigger

  1. Open Object Designer and then click Table.

  2. Select a table from the list and then click Design.

    The table opens in Table Designer.

  3. Click View and then click C/AL Code.

    The C/AL Editor opens.

    The position or the cursor in Table Designer determines the order in which triggers are displayed in the C/AL Editors. For example, if you place the cursor on a specific field, the trigger for that field appears at the top of the C/AL Editor. Scroll through the list of triggers displayed to access other triggers.

  4. Enter or modify the appropriate triggers.

See Also

Concepts

Table and Field Triggers
Triggers


Setting Relationships Between Tables

Setting Relationships Between Tables

It is common to distinguish among the following types of relationships between tables in relational database design:

  • One-to-many relationships

  • Many-to-many relationships

  • One-to-one relationships

The one-to-many relationship is the most common. If your database design model indicates that you need to set up a many-to-many relationship, then your design is probably inefficient. You can typically break down a many-to-many relationship into two one-to-many relationships. A one-to-one relationship is usually not optimal and can often be avoided by combining the two tables.

Using Relationships

If your database contains tables with related data, then you can define a relationship between them. You relate tables by specifying one or more fields that contain the same value in related records. These matching fields often have the same name in each table. You can use relationships to:

  • Validate data entries.

  • Perform lookup functions in other tables.

  • Propagate changes automatically from one table to other tables.

Table Relationships and the TableRelation Property

Table relationships are defined in Microsoft Dynamics NAV with the TableRelation property. This property allows you to define both simple and advanced table relations.

Note Note

You can define a relationship only to a field that is a member of the primary key group.

Advanced table relations are typically prefixed with a conditional statement and include filters. The following syntax is for table relations.

CopyCode image Copy Code
<TableRelation> ::=
   <TableNo>[.<FieldNo>] [WHERE ( <TableFilters> )] |
   IF ( <Conditions> ) <TableNo>[.<FieldNo>]
   [WHERE( <TableFilters> )] ELSE <TableRelation>
<Conditions> ::=
   <TableFilters>
<TableFilters>::=
   [<TableFilter> {,<TableFilter>}]
<TableFilter>::=
   <DstFieldNo>=CONST(<FieldConst>) |
   <DstFieldNo>=FILTER(<Filter>)

The following table describes each of the symbols.

Symbol | Description
TableNo | Specifies the related table.
FieldNo | Specifies a field in the related table.
Conditions | Table relations can be conditional.
TableFilters | A list of table filters.
TableFilter | A constant expression or a filter expression.
DstFieldNo | Specifies the destination field number.
Filter | A filter expression, such as 10|20..30.

Examples of Table Relationships

For example, you have an Orders table that stores orders and a Salesperson table that stores the names of all salespeople in your company. In the Orders table, you can include a Salesperson field that identifies the salesperson. By setting up a relationship between these two tables, you can check whether the Salesperson field in the Orders table contains a valid code.

For example, you have a Vendors table with all your vendors and a Currency Code table. You can create a relationship between a Currency Code field in the Vendors table and the Currency Code table. This will allow users to look up information about valid currency codes.

Furthermore, if you change one of the currency codes in the Currency Code table, then the change is automatically propagated to all tables that refer to this code.

See Also

Tasks

How to: Create a Table Relationship


How to: Create a Table Relationship

How to: Create a Table Relationship

Table relationships are defined using the TableRelation Property. This property allows you to define both simple and advanced table relationships. A typical simple table relationship consists of a table name and an optional field name. An advanced table relationship might additionally contain conditions and filters.

To create a table relationship

  1. Open Object Designer and click Table to see a list of the tables.

  2. Select a table and then click Design.

    The table opens in Table Designer.

  3. Select the field for which you want to create a relationship and view the Properties window.

  4. Set the TableRelation property value by using the following steps:

    1. In the TableRelation property value, click the AssistEdit button.

      The Table Relation window opens.

    2. Click the AssistEdit in the Table cell, select a table, and then click OK.

    3. Click the AssistEdit in the Field cell, select a field, and then click OK.

    4. Set the Condition or Filter fields, as needed.

    5. Click OK.

See Also

Concepts

Setting Relationships Between Tables


Maintaining Table Relationships on SQL Server

Maintaining Table Relationships on SQL Server

The TableRelation Property in Microsoft Dynamics NAV can be represented in SQL Server by table relationships known as foreign key constraints. These table relationships are metadata about the tables and are only intended for modeling and diagramming; they are not used to enforce data integrity. The foreign key constraints are disabled.

The table relationships in SQL Server can be accessed with external tools that can use this information to generate diagrams illustrating the structure of the database.

You can use the Maintain Relationships option on the Integration tab of the New Database and the Alter Database windows to enable and disable the table relationships on SQL Server. For more information about setting this option, see the Altering Databases - Integration Tab topic in the Microsoft Dynamics NAV Classic client help.

Requirements

There are certain requirements that must be met before a TableRelation Property can be represented on SQL Server.

To maintain a table relationship:

  • The fields forming the relationship must be of the same data type in both of the related tables. This also applies to any fields that are specified in the Table Filter field. Text and code fields are compatible as long as they have the same length.

  • The SQL Data Type Property of code fields must be the same in both tables.

  • The table filter that is part of the table relationship must contain only the FIELD filter type. Table filters of the CONST and FILTER filter type cannot be created on SQL Server.

  • Conditional relationships have one SQL Server relationship for each condition, as long as all of the criteria listed here are met by each condition.

See Also

Concepts

Setting Relationships Between Tables


How to: Synchronize Table and SQL Server Relationships

How to: Synchronize Table and SQL Server Relationships

The TableRelation property and SQL Server relationships are automatically synchronized when you create a table and when you redesign a table. However, there are some situations in which you may need to manually synchronize the relationships. Examples include after you have:

  • Deleted a table in the Object Designer.

  • Restored a database backup.

  • Imported a .fob file.

Note Note

Table relationships are not generated or maintained when you import a .txt file.

To initiate the synchronization process manually

  1. On the File menu, click Database, and then click Alter. The Alter Database window appears.

  2. Click the Integration tab.

  3. Select the Synchronize check box and click OK.

    This check box is only enabled when there are table relationships that need to be synchronized because of inconsistencies in the TableRelation property.

    If an error occurs during the synchronization process, you receive an error message informing you that a particular table has an invalid relationship. To correct this error, you must modify the TableRelation property of the table in question in the Table Designer and then manually synchronize the relationships again.

See Also

Concepts

Setting Relationships Between Tables


Creating Table Defintions from SQL Server Objects (Linked Objects)

Creating Table Defintions from SQL Server Objects (Linked Objects)
See Also

With Microsoft Dynamics NAV, you can create a table definition for a SQL Server object (user table, system table, or view) that already exists in the current database.

Defining Linked Object Table Properties

You use the LinkedObject table property to link to SQL Server objects by changing the value to Yes when creating or modifying a table description in the table designer. When you change this value to Yes, the LinkedInTransaction property becomes available.

The LinkedInTransaction property must be set to No when the Microsoft Dynamics NAV table description refers to a view that depends on objects that are outside the current database or on a linked server.

The LinkedInTransaction property allows you to read and modify data from linked server data sources, such as Microsoft Office Excel, Access, or another SQL Server. This access is not under Microsoft Dynamics NAV transaction control. This means that if a Microsoft Dynamics NAV transaction is stopped, any changes that were made during this transaction to a linked object that is outside the current database or on a linked server will remain in effect.

See Also

Concepts

Accessing Objects in Other Databases or on Linked Servers


Using Linked Objects

Using Linked Objects

When you are using a linked object, you should take the following into account:

  • The name of the SQL Server object that includes any company prefix and ($) separator must match exactly with the name of the Microsoft Dynamics NAV table.

  • You must be a member of the db_owner fixed database role in the current database.

  • As is the case with regular Microsoft Dynamics NAV tables, the object must exist in the current database and be owned by a user in the database who is a member of the db_owner fixed database role. A SQL Server view can be used to access objects outside the current database (including those residing on separate servers) or owned by other users. For more information, see Accessing Objects in Other Databases or on Linked Servers.

  • Microsoft Dynamics NAV will automatically grant the required SQL Server permissions on the object so that you can access it in the same way that regular Microsoft Dynamics NAV tables are accessed. It will then be subject to permissions assigned in the Microsoft Dynamics NAV security system.

  • The object being linked must have a SQL Server table definition that is compatible with the Microsoft Dynamics NAV table definition.

  • A view that cannot be updated in SQL Server (for example one containing computed/converted columns or unions) will also be read-only if it is used as a linked object from Microsoft Dynamics NAV. With SQL Server 2000, you can write Instead-Of triggers to define the logic that allows such a view to be updated. This logic is not part of Microsoft Dynamics NAV.

Rules for Using Linked Objects

Object modification | Rule
Column type | All columns in the object must be type compatible with those named in the Microsoft Dynamics NAV table definition. It is not necessary to name all the columns in the Microsoft Dynamics NAV table definition. For more information about type compatibility, see Identifiers, Data Types and Data Formats in the SQL Server Option for Microsoft Dynamics NAV.
SumIndexField technology | SumIndexFields cannot be defined for any object type.
View or system tables | If the object is a view or system table, a primary key must be defined, and any secondary keys may also be defined if required. These keys will only be used in Microsoft Dynamics NAV. They will have no effect on a view, its underlying objects in SQL Server, or on a system table. It is important that the data in the columns named in the primary key is unique. This will not be enforced as a physical constraint by the view or system table in SQL Server. However, Microsoft Dynamics NAV will order the data as though a primary key was physically defined. Microsoft Dynamics NAV relies on this uniqueness in order to correctly identify and order records.
View objects | If the object is a view, it can have only one column of the SQL Server timestamp type, but it does not need to have any unless BLOB fields are present in the Microsoft Dynamics NAV table definition. A timestamp column must exist in a user table.
User table or view | An IDENTITY column can be used in a user table or a view. Microsoft Dynamics NAV will ignore this column when inserting records into the table. This allows the IDENTITY column to be used as intended. Similarly, a computed column in a user table is also ignored. For a view, a column defined on a computed table column cannot be used if insert operations are required.
Temporary table | You cannot link to a SQL Server temporary table.
Multilanguage views | Multilanguage views are not created or maintained for linked objects.

Redesigning a Linked Object Table Definition

After an object has been linked, Microsoft Dynamics NAV treats it like a regular table. However, depending on the object type, SQL Server may prevent certain operations from taking place. For example, a non-updateable view cannot be updated in Microsoft Dynamics NAV, and a SQL Server error message appears if you attempt to do this. The ability to redesign the object from within Microsoft Dynamics NAV is limited; these limitations are as follows:

  • The object cannot be renamed by changing the table definition name or the company name.

  • No fields in the table definition can be renamed.

  • New fields can be added if they exist in the view and existing fields can be deleted. In either case, the definition of the view in SQL Server is not changed.

  • The primary and secondary key definitions can be changed. Also, new keys can be added and existing keys can be deleted.

  • The Microsoft Dynamics NAV field data types can be modified provided that the new type remains compatible with the column type in the view.

  • A linked user table can undergo any design changes that are applicable to a regular table that is created from within Microsoft Dynamics NAV.

  • If the DataPerCompany property of the Microsoft Dynamics NAV table definition is changed, it will result in an attempt to link to a new object. This new object will be based on the new company name. The previously linked SQL Server object will no longer be linked by the table definition.

  • The LinkedObject table property can only be changed from Yes to No for a user table.

See Also

Concepts

Creating Table Defintions from SQL Server Objects (Linked Objects)


How to: Create and Delete a Table Description

How to: Create and Delete a Table Description

You can create different kinds of Microsoft Dynamics NAV table descriptions, depending on the LinkedObject and LinkedInTransaction table property values. You must be a member of the db_owner fixed database role to create a table description.

To create a non-linked table

  • Set the value of the LinkedObject property to No.

    When you save this table, a SQL Server table that is owned by the db_owner fixed database role is created with the name you have specified (including the company name, if necessary).

    If an object with this name already exists, an error message is displayed and the table is not saved.

To create a linked object that is under transaction control

  1. Set the LinkedObject property to Yes.

  2. Set the LinkedInTransaction property to No.

    The table is saved without checking its validity. Microsoft Dynamics NAV will check that the corresponding SQL Server object exists and that it is compatible with the Microsoft Dynamics NAV table description when the table is accessed.

To create a linked object that is not under transaction control

  1. Set the LinkedObject property to Yes.

  2. Set the LinkedInTranaction property to No.

    The table is saved without checking its validity. Microsoft Dynamics NAV will check that the corresponding SQL object exists and that it is compatible with the Microsoft Dynamics NAV table description when the table is accessed.

To delete a table description

  • Set the LinkedObject property to No.

When the LinkedObject property is set to No, the SQL Server object is deleted if it is a user table. The SQL Server object is not deleted if it is a system table or a view. It can only be a system table or a view if it has been changed to one of these object types with the aid of an external tool. The LinkedObject property must be set to Yes in order to be able to link to a system table or a view.

When the LinkedObject property is set to Yes, the SQL Server object is not deleted. This means that if you create a Microsoft Dynamics NAV table with the LinkedObject property set to No and then change it to Yes, its corresponding SQL Server object is not deleted.

When you modify the LinkedInTransaction property of a Microsoft Dynamics NAV table, all access to the linked SQL Server object will be made under or outside transaction control, depending on the setting you choose.

  1. When you access data in a linked object, if the LinkedInTransaction property is set to Yes, all access to the linked object will be performed under transaction control, within Microsoft Dynamics NAV transactions. If the LinkedInTransaction property is set to No, all access to the linked object will be performed outside transaction control, independent of Microsoft Dynamics NAV transactions.


Accessing Objects in Other Databases or on Linked Servers

Accessing Objects in Other Databases or on Linked Servers

You can access objects outside the current database or server from Microsoft Dynamics NAV by linking to an appropriately defined view in the current database. You can create a view definition outside of Microsoft Dynamics NAV that accesses data on SQL Server linked servers, which can access heterogeneous data sources. This could, for example, involve performing a join of an Oracle table, a Microsoft Office Access table, or a Microsoft Office Excel spreadsheet.

To access objects in other databases or on linked servers you must comply with the following rules:

  • You must set the LinkedInTransaction table property to No in order to use a view referring to objects outside of the current database. The ability to modify data in these objects is dependent on the data providers that the objects refer to.

  • You must be a member of the db_owner fixed database role in the current database to access objects in other databases or on linked servers.

  • All security permissions for objects in another database or on linked servers must be granted outside Microsoft Dynamics NAV to the appropriate SQL Server logins.

  • If a linked object refers to a view that accesses objects that are stored in another database on the same server, this view must be treated as though it were accessing a linked server.

See Also

Concepts

Creating Table Defintions from SQL Server Objects (Linked Objects)


Creating and Maintaining Pages

Creating and Maintaining Pages

The following sections provide an overview of how to locate Microsoft Dynamics NAV 2009 documentation about developing pages for the RoleTailored client.

In Microsoft Dynamics NAV 2009, pages provide the main way to interact with the RoleTailored client user interface. Pages are XML-based and can be displayed on multiple display targets. They are also role based to the needs of individual users.

Page Development Documentation

This documentation is intended for Microsoft Dynamics NAV 2009 developers. It is intended that this topic will help you to quickly find the information that you need.

To | See
Get a general introduction to the page object | Pages Overview
Find out what page types are available and to understand how to choose the right one | Touring the RoleTailored Client Pages
Learn about new and changed properties that are available in Page Designer | Page Properties

Creating Pages

To | See
Learn how to create a card page | Walkthrough: Creating a Customer Card Page in Page Designer
Learn how to create a list page | Walkthrough: Creating a Customer List in Page Designer
Learn how to create a Role Center | Walkthrough: Creating a Role Center
Learn how to create a document page | Walkthrough: Creating a Document Page
Learn how to create a worksheet page | Walkthrough: Creating a Worksheet Page
Learn how to create a wizard using the navigate page type | Walkthrough: Creating a Wizard Page

Modifying Pages

To | See
Add actions to a customer list page | Walkthrough: Adding Actions to a Customer List Page
Add a FactBox to a customer list page | Walkthrough: Adding a FactBox to the Customer List Page

Adding Actions to Pages

To | See
Find the appropriate actions topic | Adding Actions to Pages
Understand how actions are intended to be used in the RoleTailored client | Actions Overview
Learn how to add actions to a page | How to: Add Actions to a Page
Learn how to promote actions to the Action Pane | How to: Add Actions to the Action Pane on Pages
Learn how to create action submenus | How to: Add Action Submenus to Pages

Running Pages

To | See
Preview a page in the RoleTailored client | How to: Run a Page

See Also

Tasks

Page Designer Troubleshooting


Pages Overview

Pages Overview

In Microsoft Dynamics NAV 2009, pages replace forms as the main way to display and organize data. Pages are displayed in the RoleTailored client, which offers users a visual experience more closely aligned to Microsoft Office and Windows. In the RoleTailored client, every user has a Role Center page, tailored to their individual needs and tasks they perform. Other types of pages, such as List pages might display lists of customers or sales orders, while others such as Document pages, focus on user tasks.

Each page has its own set of controls that should only be used with that page type. For example, Cues are only used on Role Center pages, FastTabs are used on Card and Document pages, and Fixed Layout controls are used on Worksheet pages. The following illustration shows a Card page, which is an example of several different controls on one page. It includes FastTabs, FactBoxes, Actions, and an Action Pane.

The Page Object

In Microsoft Dynamics NAV, a page is basically an XML object composed of controls, properties, actions, triggers, and code. You create page objects in Page Designer and save them in Object Designer in the same way as you save forms or other Microsoft Dynamics NAV objects.

In Page Designer, you can start by creating a blank page or choose from 10 page types. Pages must be linked to a source table, unless you want to create a Role Center or a blank page not based on a page type.

In the Page Designer window, you group controls in a hierarchy that reflects the XML structure of the page. To help you to create the correct XML layout, page designer provides you with several new properties called Types and SubTypes. These properties enable you to create controls, specify their position on the page, and how they are grouped. You set types and subtypes using the drop-down menus in Page Designer.

The following table shows Page Designer Types and SubTypes.

Type | SubType
Container | ContentArea FactBoxArea RoleCenterArea
Group | Group Repeater CueGroup FixedLayout
Field | No SubType available for this Type
Part | No SubType available for this Type

When you add controls, each row is automatically indented, although every time you add a row you can adjust indentation manually with right and left indentation controls. If you indent an element in your page incorrectly, you will get an error message when you try to save and compile the page.

Use the Properties window to set your properties on a page. Properties work in the same way for pages as they do for forms, and other Microsoft Dynamics NAV objects, although there are several new and changed properties in pages. For more information, see Page Properties.

Use C/AL Globals in Object Designer to define C/AL triggers and functions on a page.

Types of Pages

The following page types are available:

  • Card

  • List

  • Role Center

  • Card Part

  • List Part

  • Document

  • Worksheet

  • Confirmation Dialog

  • List Plus

  • Navigate Page (Wizard)

For more information about page types, see Touring the RoleTailored Client Pages.

Designing Pages

In Microsoft Dynamics NAV, when you design and create pages you use the Page Designer, which is part of the Classic client Object Designer.

When you design new pages you should start by looking at the wide variety of roles, tasks, and activities in your organization. These tasks and activities should be reflected in the pages that you create, and the navigation that you add to a page. There are several different page types which you can use to help you in this process. Each page type behaves like a container or template on which you can add controls and navigation elements called actions.

Window size and the positioning are controlled automatically, depending on the display device used. The controls that you use on a page are determined by the page type that you select.

Pages are metadata driven making them more flexible than forms. They can be delivered on a wider variety of display targets which makes them more scalable. Pages have been designed to optimize performance and new enhanced controls mean that there are fewer triggers on pages than there were on forms.

You can change the behavior of pages by making changes to the properties sheet, just as you did with forms. For example you save and compile pages just like forms. You can access Properties, C/AL code, the C/AL Symbol Menu, C/AL Globals, and the Field Menu by using the same shortcuts or by using the View menu, as you did in forms.

In Object Designer, all existing page objects, and any new ones that you create are listed under the Pages button. To create a new page your must first open the New Page dialog box and then select a page type. We recommend that you always select a page type instead of creating a blank page when you design a page.

Page Controls

You can add the following page controls to a page depending on the page type you have chosen:

  • FactBox

  • FastTab

  • Cue

  • HomePart

  • ChartPart

  • PagePart

  • SystemPart

  • Action Pane

  • Filter Pane

For more information about controls, see Touring the RoleTailored Client Pages.

Adding Navigation to Pages

All pages contain menu items and navigation controls called Actions.

In Microsoft Dynamics NAV there are three categories of Actions:

  • Action Items

  • Related Information

  • Reports

Role Center pages have their own navigation pane and the following actions:

  • Activity Buttons

  • Home Items

You can access Action Designer from Page Designer. When you want to add actions to a page, open Page Designer, click the last available row at the bottom of the page, click View, and then click Actions to open Action Designer. You use the Action Designer in the same way as you use Page Designer. You add new actions as rows in the Action Designer window, and set Action Types and SubTypes using the drop-down menus. Each action also has its own set of properties available in the Properties window.

For more information about actions, see Actions Overview.

Best Practices for Designing Pages

We recommend that you simplify the user experience by reducing what users see by default. You can promote the information that the users most frequently need to see and hide the less important information. For example:

  • Place common tasks in the Action pane

  • Organize information pages under FastTabs and, by default, hide the FastTabs that are infrequently visited.

  • Use one to three FactBoxes on a page to provide supplementary information and a place for adding notes.

See Also

Tasks

Touring the RoleTailored Client Pages

Concepts

Actions Overview


How to: Create a Page

How to: Create a Page

Similar to forms in the Classic client, pages are objects in the RoleTailored client for viewing and editing data. When you create a new page for the RoleTailored client, consider the page's business purpose, including which user uses it and what tasks the user needs to perform. There are ten page types from which you can choose, including:

  • Role Center pages, which are home pages for a specific user role such as account manager or sales order processor.

  • List pages, which display multiple records on a page.

  • Card pages, which are used to edit individual customer or item records.

The page type determines which controls, parts, and properties are valid for the page. For example, FactBoxes are not allowed on all page types. For more information about page types, see Touring the RoleTailored Client Pages.

You can choose to create a blank page and build a page from scratch, or if you are running Microsoft Dynamics NAV 2009 SP1, you can use the page wizard to create a specific type of page.

To create a blank page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. If your page is associated with a table, in the Table text box, click the AssistButton, select a table, and then click OK.

  4. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

    Note Note

    If you are running Microsoft Dynamics NAV 2009, you can select Create blank page of type, select the page type, and then continue to step 9.

  5. In the Caption field of the first row, which has the type Container and the subtype ContentArea, type some descriptive text, such as contentcontainer.

    Note Note

    This text is used internally for identification purposes and does not appear in the RoleTailored client.

  6. Click on another row to automatically complete the Name field.

  7. By default, the page is a Card page type. To change to another page type, select a blank row, and on the View menu, click Properties.

  8. Locate the PageType property, and then set the Value field to the page type you want. For more information on the different page types, see Touring the RoleTailored Client Pages.

  9. Save your page. On the File menu, click Save As. The Save As dialog box appears.

  10. Under ID, enter the page ID. Pages use the same ID range as forms.

  11. Under Name, enter a name.

  12. Click OK. Your page is saved.

  13. Complete the page design by adding additional controls, parts, and actions as necessary. For more information, see:

    • Page Designer Walkthroughs

    • Adding Actions to Pages

    • Creating Activity Buttons for the Navigation Pane

    • How to: Run a Page

Creating a Page Using the Wizard

Note Note

The page wizard is only available in Microsoft Dynamics NAV 2009 SP1.

The Classic client includes a wizard that creates specific page types. In the page wizard, you choose a page type, and the page wizard automatically adds some content and controls to the page for you.

The page wizard is designed to help you get started on creating page by adding the basic content and controls. The wizard has limitations and may not add all content that you want on a page, as outlined in the following table:

What the wizard does do What the wizard does not do

  • Sets the page type.

  • Associates a selected table with the page.

  • Adds FastTabs and selected fields.

  • Adds single lists with selected fields as columns.

  • Add page controls and parts that include Cues, FactBoxes, Outlook parts, Notes, My Notes, RecordLinks, and FixedLayouts.

  • Add actions.

Depending on the page's type and complexity, you typically need to manually make changes to a page after you use the wizard.

To create a page using the wizard

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. Click Create page using wizard, and then click the page type from the list.

  4. To specify the table with which your page is associated, in the Table text box, click the AssistButton, select a table, and then click OK.

    Note Note

    RoleCenter page types are not associated with a table. To complete the wizard, select any table.

  5. Click Finish.

    The new page appears in Page Designer.

  6. Save the page. On the File menu, click Save As. The Save As dialog box appears.

  7. Under ID, enter the page ID. Pages use the same ID range as forms.

  8. Under Name, enter a name.

  9. Click OK. Your page is saved.

  10. Complete the page design by adding additional controls, parts, and actions as necessary. For more information, see:

    • Page Designer Walkthroughs

    • Adding Actions to Pages

    • Creating Activity Buttons for the Navigation Pane

    • How to: Run a Page

See Also

Tasks

How to: Add FastTabs to a Customer Card Page
How to: Create a FactBox to Display Customer Data

Concepts

Creating and Maintaining Pages
Pages Overview


How to: Add FastTabs to a Customer Card Page

How to: Add FastTabs to a Customer Card Page

In this topic you learn how to add a FastTab control to a customer card page. FastTabs replace tabs and enable you to place data in groups on card or task pages. If a group is expanded you see all the fields in a group. If it is collapsed you just see the summary line. The summary line is the header that displays a name for the group, such as 'Communication' and can include promoted fields such as 'E-mail'. Promoting fields to the summary line enables you to present key information to the user, even if the control is collapsed.

Organizing data using FastTabs helps users to find key information quickly, while at the same time giving an overview of areas that otherwise would remain hidden. For example, the customer card page displays customer information in the following categories: General, Communication, Invoicing, Payments, Shipping, and Foreign Trade. Each category is a separate group that can be expanded or collapsed, making it easier for users to focus on one area at a time. On task pages, a FastTab typically represents a single step in a task.

Adding a FastTab Control to a Card Page

To add a FastTab control to a card page

  1. Open Object Designer, click Page. Select a card page that you have created from the list of available pages, and then click Design.

    For more information about how to create card pages, see Walkthrough: Creating a Customer Card Page in Page Designer.

  2. In Page Designer, click the first available row in your blank card page. Type a name for your control in the Name field. Click the Caption field and the other fields are completed automatically. By default, Type is set to Container and SubType is set to ContentArea. Keep the default values.

  3. In the second row, type a name for your group in the Name field. Set Type to Group and SubType to Group.

  4. In the third row, set Type to Field.

  5. On the View menu, click Field Menu.

    In the Field Menu window, select fields from the Customer table. Select multiple fields by holding down the CTRL key, while you click the following fields:

    • No.

    • Name

    • Address

    • City

    • Phone No.

    When you have completed this procedure, these fields will be displayed in your FastTab control.

    If the OK and Cancel buttons are unavailable, see Page Designer Troubleshooting for more information.

    Note Note

    You can only select fields from the Field Menu if your page has a source table. Remember to select a source table in the New Page dialog when you create your page.

  6. Click OK. A message box appears with the following message: "Do you want to add the fields that are selected in the field menu?" Click Yes.

  7. Click on the View menu, click Properties. In the Properties window, type a name in Caption. The CaptionML field is completed automatically.

  8. Close the Page Designer window and save your changes. If you created a new page, select a page ID number in the 50000 range, type a name for your page, and then click OK.

    Repeat the same procedure to add more FastTab groups to your page.

See Also

Tasks

Walkthrough: Creating a Customer Card Page in Page Designer
Page Designer Troubleshooting


How to: Create a FactBox to Display Customer Data

How to: Create a FactBox to Display Customer Data

Note Note

This procedure describes how to create a FactBox by using the page wizard, which is only available in Microsoft Dynamics NAV 2009 SP1. For information on how to create a FactBox in Microsoft Dynamics NAV 2009, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

A FactBox displays additional information to the user in a pane located on the right of the main page display area.

There are three types of FactBoxes:

  • Page part

  • System part

  • Chart part

For example, on the customer list page you can see four FactBoxes: Customer Sales History - Sell-to Customer, Customer Statistics - Bill-to Customer, Links, and Notes. The first two are page parts based on existing pages. Links and Notes are system parts that are predefined. Other available system parts are Outlook, MyNotes, and Record Links.

FactBoxes can be used with the following page types:

  • Card

  • List

  • Document

  • Worksheet

  • List Plus

  • Navigate

If users do not want to see information displayed in a FactBox, they can collapse the control or hide it. FactBoxes can be hidden or customized to show more or fewer fields, using the customize dialogs.

A FactBox is also a page, so you must first create it in Page Designer, allocate it a source table, and then link it to a page where you want it to appear.

A business user, such as the order processor, can benefit from having additional FactBoxes on a page. For example, when the order processor uses page 22, the Customer list page, it would be useful to see information such as Outstanding Orders when different customers are selected in the list. You can do this by creating a Customer Orders FactBox that only displays specific fields from the Customer table related to outstanding customer orders.

Creating a FactBox to Display Outstanding Customer Orders

To create a FactBox to display outstanding customer orders

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. Click Create page using wizard, and then click CardPart from the list.

  4. To associate the page with the Customer table, in the Table text box, click the AssistButton, select table 18, and then click OK.

  5. Click OK to continue the wizard.

  6. On the Card Part Page Wizard dialog box, use the arrow keys to move the following fields from Available Fields list to the Field Order list:

    • Outstanding Orders (LCY)

    • Shipped Not Invoiced (LCY)

  7. Click Finish.

    The new page appears in Page Designer.

  8. Save the page. On the File menu, click Save As. The Save As dialog box appears.

  9. Under ID, enter the page ID. Pages use the same ID range as forms.

  10. Under Name, enter Customer Orders Fact Box.

  11. Click OK. Your page is saved.

  12. To run your page, in Object Designer, select the page, and then click Run. The RoleTailored client opens and displays your new FactBox page.

See Also

Tasks

Walkthrough: Adding a FactBox to the Customer List Page
Page Designer Troubleshooting


How to: Open a Card Page from an Item in a List

How to: Open a Card Page from an Item in a List

You can associate items in a list page with a related card page so that when a user double-clicks the list item, the card page for that item is launched. The CardFormID property is used to associate an item in a list with a specific card page. For example, you can use it to associate a name in a customer list the related customer card.

To associate a card page with a list page

  1. With the list page open in Page Designer and with the first available empty row in Page Designer selected, from the View menu, click Properties.

    The Properties window opens.

  2. Locate the CardFormID property and click the AssistButton in the value field.

    The Page List window opens.

  3. Select a page from the list and then click OK.

See Also

Tasks

Walkthrough: Creating a Customer List in Page Designer

Reference

CardFormID Property


How to: Run a Page

How to: Run a Page

When you are developing pages, you may want to see how the pages look in the RoleTailored client. You can run and view a RoleTailored client page from Object Designer in the Classic client, or you can use command-line arguments at the command prompt, in the Run window, or in a browser. For each method, the RoleTailored client starts and opens the selected page. For command-line arguments, you have various options for opening the RoleTailored client and its pages in different modes. For example, you can specify a specific server or specific language, or you can create hyperlinks to specific pages in Microsoft Dynamics NAV. For more information, see Starting the RoleTailored Client from a Command Prompt and Creating and Running Hyperlinks.

Note Note

ConfirmationDialog pages cannot be run and previewed by using the methods described in this topic. You can only view ConfirmationDialog pages by invoking them in the RoleTailored client.

To run a page from Object Designer

  1. Open the Classic Client.

  2. On the Tools menu, click Object Designer, and then click Page.

  3. Select the page that you want to view, and then click Run.

Note Note

This Run button is only supported by Microsoft Dynamics NAV 2009 SP1.

To run a page at the command prompt

  1. At the command prompt, change to the RoleTailored client directory with the following cd command:

    CopyCode image Copy Code
    cd C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client

  2. Type the following command:

    CopyCode image Copy Code
    Microsoft.Dynamics.Nav.Client.exe Dynamicsnav:////runpage?page=nn

    Substitute nn with the ID of the page that you want to view.

  3. Press ENTER.

    The RoleTailored client opens and displays the page.

To run a page from the Run window

  1. On the taskbar, click Start, and then click Run.

  2. In the Run window, type the following command:

    CopyCode image Copy Code
    Microsoft.Dynamics.Nav.Client.exe Dynamicsnav:////runpage?page=nn

    Substitute nn with the ID of the page that you want to view.

  3. Click OK.

    The RoleTailored client opens and displays the page.

To run a page from a browser

  1. Open the browser.

  2. In the address bar, type the following command:

    CopyCode image Copy Code
    Dynamicsnav:////runpage?page=nn

    Substitute nn with the ID of the page that you want to view.

  3. Press Go.

    The RoleTailored client opens and displays the page.

See Also

Concepts

Starting the RoleTailored Client from a Command Prompt
Creating and Running Hyperlinks


Page Properties

Page Properties

When you create pages in Page Designer in Microsoft Dynamics NAV, you set properties on the page that describe and format the page and the controls on the page. For more information, see How to: Create a Page.

Expand image Properties for a Page

The following table lists the properties that you set for a page in the Properties window.

Property Description

ID

The ID of the page—must be unique among pages.

Name

The name of the page.

Caption

The caption shown in the title bar. For example, the default value in English (United States) is the same as the name of the page.

CaptionML

The list of translations of the object’s caption.

Editable

Indicates if the page can be edited.

Note Note

Set the value of this property as an expression.

For more information, see Editable Property.

Description

Sets the description of the page. This description is for internal use and does not appear to end users.

For more information, see Description Property.

Permissions

Sets whether a database object has additional permission required to perform some operations on one or more tables. The operations can be to read, insert, modify, and delete data.

For more information, see Permissions Property.

PageType

Specifies how the page is displayed in the RoleTailored client

The following options are available:

  • Card

  • List

  • RoleCenter

  • CardPart

  • ListPart

  • NavigatePage

  • Document

  • Worksheet

  • ListPlus

  • ConfirmationDialog

For more information, see PageType Property.

InstructionalTextML

Sets the multilanguage value of the InstructionalText of the object. Use this property as a label.

The property can be set on a group control.

For more information, see InstructionalTextML Property.

CardFormID

Use this property to associate an item in a list page with a card page. This is similar to the card to list functionality in forms.

For example, see page 21, Customer Card. This page is associated with page 22, the Customer List page. Setting the CardFormID property enables users to launch the customer card when they double-click a customer in the list.

Note Note

The CardFormID property must only be used with lists.

For more information, see CardFormID Property.

DataCaptionExpr

Sets a C/AL expression that is evaluated and displayed to the left of the page caption.

For more information, see DataCaptionExpr Property.

SourceTable

Sets the ID of the table from which this form will display records.

For more information, see SourceTable Property.

SourceTableView

Sets the key, sort order, and filter you want to use to determine the view of the source table presented to the user.

For more information, see SourceTableView Property.

InsertAllowed

Sets a value to specify whether users can add records while using the page.

For more information, see InsertAllowed Property.

ModifyAllowed

Sets the value to determine whether users can modify records while using this page.

For more information, see ModifyAllowed Property.

DeleteAllowed

Sets a value that specifies whether users can delete records while using the page.

For more information, see DeleteAllowed Property.

DelayedInsert

Sets a value that specifies whether a must user leaves a record before it is inserted into the database. By default, new records are inserted when the user leaves the control that shows the primary key in the table.

For more information, see DelayedInsert Property.

MultipleNewLines

Sets a value that determines whether users can add multiple new lines between records.

For more information, see MultipleNewLines Property.

AutoSplitKey

Sets whether a key is automatically created for a new record placed between the current record and the previous record.

For more information, see AutoSplitKey Property.

DataCaptionFields

Sets the fields that appear to the left of the page caption that display the contents of this table.

For more information, see DataCaptionFields Property.

SourceTableTemporary

Sets if the source table is a temporary table.

For more information, see SourceTableTemporary Property.

LinksAllowed

Sets if links are allowed.

For more information, see LinksAllowed Property.

PopulateAllFields

Sets whether fields are filled out automatically with a single filter value when a new record is inserted in a table.

For more information, see PopulateAllFields Property.

Pages contain different kinds of controls. The following table sections describe the properties that you set for controls in the Properties window.

Expand image Properties on Container Controls

The following table lists the properties that you set for a page in Page Designer. For more information, see How to: Create a Page.

Property Description

ID

The ID of the page—must be unique among controls on this page.

Name

The name of the control.

Caption

The caption shown in the title bar. For example, the default value in English (United States) is the same as the name of the page.

CaptionML

The list of translations of the object’s caption.

Description

Sets the description of the page. This description is for internal use and does not appear to end users.

For more information, see Description Property.

ContainerType

Sets the type of the container control. The following options are available:

  • ContentArea

  • FactBoxArea

  • RoleCenterArea

For more information, see ContainerType Property.

Expand image Properties on Group Controls

The following table lists the properties that you set for group controls in the Properties window. For more information, see How to: Create a Page.

Property Description

ID

The ID of the group—must be unique among controls on this page.

Name

The name of the control.

Visible

Sets the visibility of a control.

Note Note

Set the value as an expression.

For more information, see Visible Property.

Enabled

Indicates if a field or key is activated or deactivated, or if a control can respond to user-generated events.

Note Note

Set the value as an expression.

For more information, see Enabled Property.

Editable

Indicates if the control can be edited.

Note Note

Set the value as an expression.

For more information, see Editable Property.

Caption

The caption shown in the title bar. For example, the default value in English (United States) is the same as the name of the page.

CaptionML

The list of translations of the object’s caption.

Description

Sets the description of the control. This description is for internal use and does not appear to end users.

For more information, see Description Property.

InstructionalTextML

Sets the multilanguage value of the InstructionalText of the object. Use this property as a label.

GroupType

Sets the type of the group control.

The following options are available:

  • Group

  • Repeater

  • CueGroup

  • FixedLayout

For more information, see GroupType Property.

IndentationColumnName

Sets the hidden column that controls the indentation of rows on a list page. This property can be set to a field or variable of type Integer.

See page 16, Chart of Accounts, for an example of row indentation.

For more information, see IndentationColumnName Property.

IndentationControls

Sets the indentation level of field controls on a list page.

You set the indentation levels in the Indent Controls window, which lists all field controls within a group container on a list page.

In the Properties window, the indented fields appear as comma-separated values in the IndentationControls property.

Note Note

The IndentationColumnName property is required when you use the IndentationControls property.

For more information, see IndentationControls Property.

FreezeColumnID

Sets that the last column in a repeater control is frozen.

Note Note

If you use this property, all columns that precede it are also frozen.

ShowAsTree

Use this property to change the indentation of rows on a list page to a tree view. If you enable this property you can expand or collapse indented rows on a list page.

For more information, see ShowAsTree Property.

Expand image Properties on Field Controls

The following table lists the properties that you set for field controls in the Properties window. For more information, see How to: Create a Page.

Property Description

ID

The ID of the field—must be unique among controls on this page.

Name

The name of the control.

Visible

Sets the visibility of a control.

Note Note

Set the value as an expression.

For more information, see Visible Property.

Enabled

Indicates if a field or key is activated or deactivated, or if a control can respond to user-generated events.

Note Note

Set the value as an expression.

For more information, see Enabled Property.

Editable

Indicates if the control can be edited.

Note Note

Set the value as an expression.

For more information, see Editable Property.

HideValue

Sets if the value of the field is hidden from the user.

Note Note

Set the value as an expression.

For more information, see HideValue Property.

Caption

The caption shown in the title bar. For example, the default value in English (United States) is the same as the name of the page.

CaptionML

The list of translations of the object’s caption.

MultiLine

Sets if the field can display multiple lines of text.

For more information, see MultiLine Property.

ToolTip

Sets whether tooltips are provided for the given object. The tooltip value is taken from the ToolTipML property if this property is set.

For more information, see ToolTip Property.

ToolTipML

Sets the text used tooltip for a control.

For more information, see ToolTipML Property.

Description

Sets the description of the control. This description is for internal use and does not appear to end users.

For more information, see Description Property.

OptionCaption

Sets the text string options that are displayed to the user.

For more information, see OptionCaption Property.

OptionCaptionML

Sets the strings that are displayed to the user for selecting an option.

OptionCaptionML is only used if the field has an OptionString property.

For more information, see OptionCaptionML Property.

DecimalPlaces

Sets display and storage requirements for the value of the field if the field type is decimal.

For more information, see DecimalPlaces Property.

Title

Set whether the first letter in each word the user types is capitalized.

For more information, see Title Property.

MinValue

Sets the minimum value for a field.

For more information, see MinValue Property.

MaxValue

Sets the maximum numeric value for a field.

For more information, see MaxValue Property.

NotBlank

Sets a value that specifies whether users must enter a value in the selected field.

For more information, see NotBlank Property.

CharAllowed

Sets the range of characters the user can enter into this field or text box.

For more information, see CharAllowed Property.

ValuesAllowed

Sets the values that are allowed in the field.

For more information, see ValuesAllowed Property.

BlankNumbers

Indicates whether the system will clear a range of numbers as it formats them.

For more information, see BlankNumbers Property.

BlankZero

Indicates whether the system displays zeros (0) and No.

For more information, see BlankZero Property.

AutoFormatType

Determines how data is formatted.

For more information, see AutoFormatType Property.

AutoFormatExpr

Determines how data is formatted.

For more information, see AutoFormatExpr Property.

SourceExpr

Sets the source expression for this control.

For more information, see SourceExpr Property.

TableRelation

Defines relationships to other tables. For more information, see TableRelation Property.

Importance

Sets the amount of information that is visible in a window or dialog box.

For more information, see Importance Property.

CaptionClass

Controls the caption that is used in the label of a field in a database table or in the label of a control on a form.

For more information, see CaptionClass Property.

DrillDownFormID

Sets the ID of the form to use as a drill-down.

For more information, see DrillDownFormID Property.

LookupFormID

Sets the ID of the form to use as a lookup.

For more information, see LookupFormID Property.

Lookup

Sets a lookup for the field.

For more information, see Lookup Property.

DrillDown

Sets a drill-down for the field.

For more information, see DrillDown Property.

AssistEdit

Sets an ellipsis (…) for the field.

For more information, see AssistEdit Property.

ClosingDates

Sets a value that determines whether users can enter a closing date in this field.

For more information, see ClosingDates Property.

Numeric

Sets a value that requires users to enter only numbers in the field.

For more information, see Numeric Property.

DateFormula

Sets a date formula used to verify that the date the user enters is correct.

For more information, see DateFormula Property.

ExtendedDatatype

Sets the extended data type of a control. The value of this property overrides the value of the table field.

For more information, see ExtendedDataType Property.

Expand image Properties on Part Controls

The following table lists the properties that you set for part controls in the Properties window. Parts are used to build FactBox areas. For more information, see How to: Create a Page.

Property Description

ID

The ID of the part—must be unique among controls on this page.

Name

The name of the control.

Visible

Sets the visibility of a control.

Note Note

Set the value as an expression.

For more information, see Visible Property.

Enabled

Indicates if a field or key is activated or deactivated, or if a control can respond to user-generated events.

Note Note

Set the value as an expression.

For more information, see Enabled Property.

Editable

Indicates if the control can be edited.

Note Note

Set the value as an expression.

For more information, see Editable Property.

Caption

The caption shown in the title bar. For example, the default value in English (United States) is the same as the name of the page.

CaptionML

The list of translations of the object’s caption.

ToolTip

Sets whether tooltips are provided for the given object. The tooltip value is taken from the ToolTipML property if this property is set.

For more information, see ToolTip Property

ToolTipML

Sets the text used tooltip for a control.

For more information, see ToolTipML Property.

Description

Sets the description of the control. This description is for internal use and does not appear to end users.

For more information, see Description Property.

SubFormView

Sets the table view for a subform.

For more information, see SubFormView Property.

SubFormLink

Sets a link to a subform from the main form.

For more information, see SubFormLink Property.

ProviderID

Sets the ID of the object that provides data to this part.

For more information, see ProviderID Property.

PartType

Sets the type of part you want to display in a FactBox.

The following options are available:

  • Page

  • System Part

    For example, Outlook or Notes.

  • Chart Part

Note Note

If you set the PartType property, you must also set one of the following properties: PagePartID, SystemPartID, and ChartPartID.

For more information, see PartType Property.

PagePartID

Sets a link to another page.

For more information, see PagePartID Property.

SystemPartID

Adds predefined system parts to the FactBox area.

The following options are available:

  • Outlook

  • Notes

  • MyNotes

  • RecordLinks

  • None

For more information, see SystemPartID Property.

ChartPartID

Sets the ID of the chart to add to the page.

For more information, see ChartPartID Property.

Expand image Properties on Actions

The following table lists the properties that you set for actions in the Properties window. Actions can be added to pages and Cue groups. For more information, see How to: Add Actions to a Page.

Property Description

ID

The ID of the action—must be unique among actions on this page.

Name

The name of the control.

Type

The type of the action.

The following options are available:

  • ActionContainer

  • ActionGroup

  • Action

  • Separator

For more information, see Actions Overview.

SubType

The subtype of an action of type ActionContainer.

The following options are available:

  • ActionItems

  • NewDocumentItems

  • RelatedInformation

  • Reports

  • HomeItems

  • ActivityButtons

For more information, see Actions Overview.

Visible

Sets the visibility of a control.

Note Note

Set the value as an expression.

For more information, see Visible Property.

Enabled

Indicates if a field or key is activated or deactivated, or if a control can respond to user-generated events.

Note Note

Set the value as an expression.

For more information, see Enabled Property.

RunFormMode

Specifies in which mode a page is opened.

The following options are available:

  • View

  • Edit

  • Create

Caption

The caption shown in the title bar. For example, the default value in English (United States) is the same as the name of the page.

CaptionML

The list of translations of the object’s caption.

ToolTip

Sets whether tooltips are provided for the given object. The tooltip value is taken from the ToolTipML property if this property is set.

For more information, see ToolTip Property.

ToolTipML

Sets the text used tooltip for a control.

For more information, see ToolTipML Property.

Description

Sets the description of the control. This description is for internal use and does not appear to end users.

For more information, see Description Property.

Image

Sets the name of the image that you want to associate with an action object.

For more information, see Image Property.

Promoted

Sets the value that indicates whether the selected action is promoted to the Actions Pane.

For more information, see Promoted Property.

PromotedCategory

Sets a category for a promoted action.

The following options are available:

  • New

  • Process

  • Report

For more information, see PromotedCategory Property.

PromotedIsBig

Sets a value that indicates whether the promoted action is displayed on the Actions Pane with a large icon.

For more information, see PromotedIsBig Property.

Ellipsis

Sets a value that specifies whether an ellipsis (...) is appended to the caption of the action.

For more information, see Ellipsis Property.

ShortCutKey

Sets a shortcut key for selecting a menu item.

For more information, see ShortCutKey Property.

RunObject

Sets the object that the action runs.

For more information, see RunObject Property.

RunFormView

Sets a specific table view for the form you launch from this control.

For more information, see RunFormView Property.

RunFormLink

Sets up a link to the form you are launching.

For more information, see RunFormLink Property.

RunFormOnRec

Sets the same record on the form you launch from this control as is already displayed on the current form.

For more information, see RunFormOnRec Property.

InFooterBar

Specifies if the action should be viewed as an action in the lower part of the page.

For more information, see InFooterBar Property.

Expand image See Also

Tasks

How to: Create a Page
How to: Add Actions to a Page
How to: Create a FactBox to Display Customer Data

Concepts

Pages Overview
Actions Overview
C/SIDE Reference Guide


Adding Actions to Pages

Adding Actions to Pages

In the RoleTailored client for Microsoft Dynamics NAV, menu items are called actions. The topics in this section provide information about creating and modifying actions on pages. Creating actions can include adding Action Items to a page, using Action Designer, configuring Home Items on a user Role Center, or adding Reports to a page.

Actions Documentation

This documentation is intended for Microsoft Dynamics NAV developers. It is intended that this topic will help you quickly find the information about actions that you need.

To | See
Learn about actions in the RoleTailored client. | Actions Overview
Learn how to add actions to a page. | How to: Add Actions to a Page
Learn how to add promoted actions to the Action Pane. | How to: Add Actions to the Action Pane on Pages
Learn how to create actions submenus. | How to: Add Action Submenus to Pages

See Also

Tasks

Page Designer Troubleshooting


Actions Overview

Actions Overview

In the RoleTailored client for Microsoft Dynamics NAV, menu items are called actions. Actions are displayed at the top of each page as menu buttons. In this topic, you learn about different kinds of actions, and how you can enable users to quickly locate the actions they want to use.

Pages can have the following actions.

Types of actions | Used on | Description | Example
Actions | Role Center, list, card, and task pages | User tasks, also known as functions in Classic client. | Post a sales order
Related Information | List, card, and task pages | Links to other pages in Microsoft Dynamics NAV. | Prices
Reports | Role Center, list, card, and task pages | A list of available reports. | Customer Top 10 List
New Document | List, card, and task pages | A submenu of Actions, under New. Opens a new Microsoft Dynamics NAV document. | New sales invoice
Promoted Actions | List, card, and task pages | Provide quick access to common tasks. | Post and print a sales order
Home Items | Role Center pages | Menu items on the Role Center navigation pane. | Customers
Activity Buttons | Role Center pages | Menu buttons for a secondary activity, such as posted documents. | Posted sales invoices
Note Note

You should not create actions submenus or promote actions on a Role Center page.

Actions replace Classic client form menu items. When you click an Action button, a drop-down menu is displayed enabling you to perform a task, access related information, or view a report.

Each page has a different set of actions depending on the page type, and the processes that the page supports. In order to create the appropriate set of actions for a particular page, you should have a good understanding of your customer's business processes.

Each process in an organization has several actions associated with it. You should try to create a full set of actions that mirror all tasks and processes that are performed.

Example: The Sales Orders list page at CRONUS International contains all actions related to processing sales orders. During user configuration and personalization, some of these actions may be hidden or promoted to the Actions Pane. Therefore, you must initially create a full set of actions for the customer.

Types of Actions

The following sections describe actions available in the RoleTailored client.

Actions

The Actions button is displayed on the menu bar of all page types.

It opens a drop-down menu giving you a choice of tasks. For example, if you click the Actions button on page 22, the Customers list page, you can select one of the following system actions:

  • View

  • Edit

  • New

  • Delete

  • Notes

  • Links

  • Open in New Window

  • Refresh

  • Clear Filter

  • Print Page

These are the actions that you would expect to see on all list pages.

This menu also contains two other actions that are more specific to the business processes on the Customers list page:

  • Cash Receipt Journal

  • Sales Journal

These two actions directly help the order processor to process customer payments. They are regular daily tasks, so must be on the Actions menu, and promoted to the Actions Pane.

You can add actions to the Actions menu, group actions together under action submenus, or promote them to the Action Pane. You cannot create submenus or promote actions on a Role Center page.

Related Information

The Related Information button is displayed after Actions on the menu bar. Rather than providing tasks for the user, this menu provides additional information by taking the user to a specific page in Microsoft Dynamics NAV.

Example: On the Customers list page, the order processor can select Sales, and then click Prices to go to the prices page. This could save the order processor time looking up prices, when creating a customer order.

Note Note

You should not add a Related Information action to a Role Center page.

Reports

The Reports button is displayed after Related Information on the menu bar. The reports menu lists the reports most relevant to a page. If a user does not require a reports menu, then the button is hidden.

Example: On page 9006, the Order Processor Role Center, the order processor can click Reports, and view her Customer - Top 10 List.

New Document

The New Document action is a submenu of Actions. You can use this action to open new documents within Microsoft Dynamics NAV, without searching through the whole application. When you create a New Document submenu in Action Designer, you must use the NewDocumentItems SubType.

Example: On the Customers list page, if the order processor wants to create a new invoice, she can open the New Sales Invoice page directly from the Actions menu. This is useful as she creates new sales invoices daily.

Note Note

You should not add a New Document Item submenu to a Role Center page.

Home Items

Home Items are actions displayed under the Home button, on the Role Center navigation pane. This navigation has a tree structure, and each node in the tree links to a list page.

The user Role Center is like a home page, and home items in the navigation pane are links to a users most useful list pages. For example, on page 9006, the Order Processor Role Center has twelve top-level menu items in the navigation pane, all related to processing sales orders. Each of these can also have sub-home items.

Activity Buttons

If there are too many activities to fit on the Role Center without scrolling, then activity buttons can be used to group other important processes together.

Example: The Order Processor Role Center could have activity buttons called Approving Web Orders, or Sales Forecasting. These are secondary activities for the order processor, so do not need to be placed under the Home button.

Each activity button has its own navigation pane, with links to list pages and can be configured in the same way as the user Role Center.

Promoted Actions

Promoted actions are existing actions in the Actions, Related Information or Reports menu that are also displayed in the Action Pane. In the RoleTailored client, the Action Pane is located just below the menu bar.

Promoted actions provide quick access to common tasks, since users do not have to click through a menu to access them. You can promote any command from the existing actions menus to the Action Pane. If there are no promoted actions, the Action Pane remains hidden.

Promoted actions can be put into one of the following categories:

  • New

  • Process

  • Reports

Each promoted action has an icon associated with it. You can accept a default icon for your promoted action or choose to use a larger icon, making it more prominent to the user. Use the Properties window in the Action Designer to set the size and location of an icon.

Example: On the Sales Orders list page, Post is promoted to the action pane, and placed in the Process group. This helps the order processor in her work, since posting sales orders is one of her most important daily tasks.

Note Note

End users can promote actions to the Action Pane as part of their personalization options.

See Also

Tasks

Walkthrough: Adding Actions to a Customer List Page
How to: Add Actions to a Page
How to: Add Actions to the Action Pane on Pages


How to: Add Actions to a Page

How to: Add Actions to a Page

This topic shows how to create new actions, how to add actions to a page, and how to preview them in the RoleTailored client. In Microsoft Dynamics NAV, actions can be displayed on the menu bar of all pages and grouped together under the following actions buttons:

  • Actions

  • Related Information

  • Reports

Before putting an action on a page you should think about the business processes that the action supports. For example, on page 42, the Sales Orders list page, the Actions button contains actions for all tasks related to processing sales orders. Creating these actions can make it easier for the order processor to perform her daily tasks, such as posting sales orders and creating new customer orders.

For more information, see Actions Overview.

Adding Actions to a Page

To create a new action you must use Action Designer. Action Designer is a tool in Page Designer that enables you to add actions to the menu bar.

To add an action to a page

  1. Open the Classic client, click Tools, and then click Object Designer.

  2. In Object Designer, select a page, and then click Design to open Page Designer.

  3. To open Action Designer, select the first empty row, click View, and then click Actions.

    Note Note

    Actions can only be linked to a page, or to a group that has a subtype of Group or CueGroup. Actions cannot be linked to fields, containers, or parts on a page.

  4. Select the first blank row in Action Designer, type a Name, and then type a Caption for your action.

  5. In the Type field, select one of the following Types:

    • ActionContainer

    • Separator

    • ActionGroup

    • Action

    For example, if you want to create a container for your actions, select ActionContainer.

  6. In the SubType field, select one of the following SubTypes:

    • NewDocumentItems

    • ActionItems

    • RelatedInformation

    • Reports

    • HomeItems

    • ActivityButtons

    For example, if you want to put your action in the Actions menu, select ActionItems.

  7. Click in the second row, set action Type to Action. Your action is indented automatically under the ActionContainer. Click the third row, and then click the second row again. The Name field in this row is filled in automatically.

    You can use the right and left arrow buttons in Action Designer to adjust indentation, and use the up and down arrow buttons to move an action in the hierarchy.

    Note Note

    If you insert a new row to add a new action to the list, indentation is not automatic, so always check the indentation on your actions. If it is not correct you will get an error when you compile.

  8. With your action selected, click View, and then click Properties. Set the RunObject property to create an action that opens another page, for example, page 42, Sales Orders.

    Note Note

    In Action Designer, actions can be assigned to a page by setting the RunObject property, or by adding a C/AL trigger to a code unit.

  9. Set the Caption and CaptionML properties to make the action visible in the Actions menu.

  10. Save and compile the page.

  11. To preview an action in the RoleTailored client, in Object Designer, select the page and click Run. For more information about running a page, see How to: Run a Page.

Note Note

If the RoleTailored client is already open, you will not see changes to HomeItems or ActivityButtons until to you close and restart it.

See Also

Tasks

Walkthrough: Adding Actions to a Customer List Page

Concepts

Actions Overview


How to: Add Actions to the Action Pane on Pages

How to: Add Actions to the Action Pane on Pages

Actions in the Action Pane are called promoted actions. Promoted actions are copies of existing actions in the command bar that are displayed in the Action Pane and provide quick access to common tasks, because users do not have to look through a menu to find them. For example, on the Customer Card page, you can promote an action to create a new sales order to help the salespeople do their work, because creating sales orders is one of their most important daily tasks. The following figure illustrates the Action Pane on a Customer Card page.

Action Pane with four categories.

Promoted actions can be organized under different categories. In this illustration, the categories are New, Tasks, Reports, and Discounts. The order of actions under a category is determined by its order in the Action Designer. You define the caption for each category. For more information on defining the promoted categories, see How to: Define Promoted Action Categories Captions for the Action Pane.

When you promote an action to the Action Pane, you can set up an image that displays with the action. If you do not set up an image yourself, then a default image is used. For more information about promoted action images, see How to: Set an Image on an Action.

Note Note

If an action does not already appear in the command bar menu, then it cannot be promoted. Also, if there are no promoted actions, then the Action Pane is hidden.

Adding a Promoted Action to a Page

To add a promoted action to a page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, select a page that already has actions, and then click Design to open the page in Page Designer. For example, select page 22, which is the Customer List page.

  3. To open Action Designer, select a blank row, and then in the View menu, click Actions.

  4. In Action Designer, select the action to promote to the Action Pane.

  5. In the View menu, click Properties.

  6. In the Properties window, set the Promoted property value to Yes.

  7. Set the PromotedCategory property to the category under which you want the promoted action to appear.

    Unless you define your own caption, the category name that you select will be used as the category's captions on the page. For more information, see How to: Define Promoted Action Categories Captions for the Action Pane.

    Note Note

    For more information about the promoted action category location in the Action Pane, see Promoted Action Category Location in the Action Pane.

  8. To assign an image to the action, set the Image property to the name of the image. For a list of images, see Action Image Library.

    Note Note

    To associate a larger icon with your action, set the PromotedIsBig property.

  9. Close the Properties window and exit Page Designer.

  10. Save and compile the page.

  11. To preview your promoted action, in Object Designer, select the page, and then click Run.

Promoted Action Category Location in the Action Pane

The locations of promoted action categories in the Action Pane are determined by their first instance in Action Designer. Starting from top of Action Designer and working down, the category of the first promoted action encountered is located on the far left of the Action Pane, the next category encountered is located to the right of the first category, and so on.

See Also

Tasks

How to: Add Actions to a Page
How to: Define Promoted Action Categories Captions for the Action Pane

Concepts

Actions Overview


How to: Define Promoted Action Categories Captions for the Action Pane

How to: Define Promoted Action Categories Captions for the Action Pane
See Also

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Promoted actions are actions that are displayed in the Action Pane of the RoleTailored client. You can organize promoted actions into different categories, where each category is indicated by a caption in the Action Pane. You define up to 10 categories for a page. The following figure illustrates a page that has promoted actions under the following categories:

  • New

  • Tasks

  • Reports

  • Discounts

Action Pane with four categories.

You assign a promoted action to a category by setting the PromotedCategory property of the action. You can choose among the following categories:

  • New

  • Process

  • Report

  • Category4

  • Category5

  • Category6

  • Category7

  • Category8

  • Category9

  • Category10

By default, these category names correspond to the captions that are displayed for the category on the page in the RoleTailored client. You will typically want to change these captions, especially the Category4 through Category10 captions.

You change category captions on a page-by-page basis and for each RoleTailored client language.

To define promoted action category captions

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, select the page, and then click Design.

  3. In Page Designer, select a blank row.

  4. In the View menu, click Properties.

  5. In the Page - Properties window, locate the PromotedActionsCategoriesML property, click the Value field, and then click the AssistButton to open the Multilanguage Editor.

  6. In the Multilanguage Editor, set the Language field to the language version of the categories that you want to define.

  7. In the Value field for the language, type the category captions as follows:

    New_caption,Process_caption,Reports_caption,Category4_caption,Category5_caption,Category6_caption,Category7_caption,Category8_caption,Category9_caption,Category10_caption

    Substitute the italic text with the text that you want for each caption. Separate each caption with a comma. The position of the caption in the list determines its corresponding category setting in the PromotedCategory property for actions, as shown in the following table:

    PromotedActionsCategoriesML caption position PromotedCategory property value

    First

    New

    Second

    Process

    Third

    Reports

    Fourth

    Category4

    Fifth

    Category5

    Sixth

    Category6

    Seventh

    Category7

    Eighth

    Category8

    Ninth

    Category9

    Tenth

    Category10

    For example, to define the captions for the figure at the beginning of this topic, you enter the following text:

    New,Tasks,Reports,Discounts

    Then, to assign a promoted action to the caption Tasks, in the Action Designer, set the PromotedCategory property value for the action to Process.

    Note Note

    You only need to define captions for the number of categories that you want to use on a page. You do not need to define captions for all 10 categrories.

  8. Close the page properties and save the page.

See Also

Tasks

How to: Add Actions to the Action Pane on Pages
How to: Add Actions to a Page
How to: Set an Image on an Action

Concepts

Actions Overview


How to: Add Action Submenus to Pages

How to: Add Action Submenus to Pages

Action submenus can be placed on pages in the RoleTailored client, under any of the three main actions menus:

  • Actions

  • Related Information

  • Reports

Create an actions submenu if you have too many actions to fit under a single actions menu. Action submenus help you to break down the numerous tasks related to a business process, into smaller, related groups.

For example, on the Customers list page, under Related Information there are two submenus with submenu actions.

Actions menu Submenu Submenu actions

Related Information

Customer

  • Ship-to Address

  • Contact

Sales

  • Prices

  • Line Discounts

The preceding table shows a small selection of submenu actions from the Customers list page. You can see that by grouping related activities together, it is possible to reduce the length of individual action menus, and make it easier for employees to find the actions they want to perform.

Creating an Action Submenu

Use Action Designer to create action submenus and individual actions to place under these menus.

You create action submenus as an Action Group type in Action Designer. Each Action Group can have any number of child elements placed below it in the hierarchy. Each row in Action Designer is indented. It is this indentation that determines the level of the action in the navigation.

To create an action submenu

  1. Open the Classic client, click Tools, and then click Object Designer.

  2. In Object Designer, select a page, and then click Design to open Page Designer. For example, select page 22, the Customers list page. You can create a submenu on a new or existing page.

  3. To open Action Designer, select an empty row at the bottom of the page, click View, and then click Actions.

  4. In Action Designer, you can see all the existing actions for the page. Right-click any row, and then click New to create a new row for your action submenu.

  5. Type a Name for your submenu item, and then click Caption. The other fields are filled in automatically.

  6. Select ActionGroup from the Type drop-down. If you select ActionGroup, the SubType field remains blank.

    You have now created an Action submenu.

  7. To add an action to your action submenu, create a new row below the ActionGroup you just created. Give your action a name, and set Type to Action in the drop-down.

  8. Use the right and left indentation arrows to indent your new action one space below ActionGroup.

    For more information, see How to: Add Actions to a Page.

  9. Save and compile the page.

  10. To preview your action submenu in the RoleTailored client, click the Start button, and then click Run. In the Run window, type the following command: Dynamicsnav:////runpage?page=<pageid>.

See Also

Tasks

How to: Add Actions to a Page

Concepts

Actions Overview


How to: Set an Image on an Action

How to: Set an Image on an Action

The RoleTailored client includes images that you can use on actions in command bar menus and promoted actions on the Action Pane. The following figure illustrates examples of images on actions.

Action Pane clip that shows images on actions

You add images to page actions with Action Designer. To add an image to an action, you must provide the name of the image. For a list of images and names, see Action Image Library.

Note Note

For information on using images on activity buttons in the navigation pane of the RoleTailored client, see How to: Add an Image to an Activity Button.

To add an image on an action

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, select the page, and then click Design.

  3. In Page Designer, select a blank row.

    You can find a blank row at the bottom of Page Designer.

  4. On the View menu, click Actions.

  5. In Action Designer, select the action for which you want the image.

  6. On the View menu, click Properties.

  7. In the Properties window, in the Value field for the Image property, type the name of the image that is found in the action image library. For more information, see Action Image Library.

  8. If the action is promoted to the Action Pane and you want the image to display in PromotedIsBig mode, then set the PromotedIsBig property to Yes.

See Also

Tasks

How to: Add Actions to a Page
How to: Add Actions to the Action Pane on Pages

Concepts

Action Image Library
Adding Actions to Pages


Action Image Library

Action Image Library

The RoleTailored client includes images that you can use on actions that display in the Action Pane and command bar menus. To add an image to an action, you must provide the name of the image. For more information, see How to: Set an Image on an Action.

Action Images

You can use the following images for actions.

Note Note

Some images are only available with Microsoft Dynamics NAV 2009 SP1. These images are marked as SP1 only.

List of Action images and their names

See Also

Tasks

How to: Set an Image on an Action

Concepts

Adding Actions to Pages


Creating and Running Hyperlinks

Creating and Running Hyperlinks

Hyperlinks enable users to send or save quick links to specific pages in Microsoft Dynamics NAV. For example, you could create a hyperlink to a specific list page, such as Customers. Hyperlinks can also be used to specify parameters, such as server name, server service, or company. You can enter hyperlinks in the Command Prompt tool, in a browser window, or directly in the Run window.

Creating Hyperlinks

To create a hyperlink, type the Microsoft Dynamics NAV executable service and then type the syntax for the hyperlink. For example: Microsoft.Dynamics.Nav.Client.exe "DynamicsNAV://MyServer/DynamicsNAV/CRONUS International Ltd./RunPage?Page=22"

This example specifies a server name, service, company, and page ID. If entered correctly it opens the RoleTailored client on page 22, the customer list page.

Building a URL

When you build a hyperlink URL, it can be structured in the following three ways:

  • DynamicsNAV://server/service/company/runpage?page=22&bookmark=0ABA0700235752C7D1

  • DynamicsNAV://server/service/company/runreport?report=901

  • DynamicsNAV://server/service/company/navigate?node=Home/Items

You can also specify the following additional parameters in a URL.

Parameter | Description | Example
Personalization ID | Specifies the unique identification used in personalization to store settings in the User Metadata table. If a personalization ID is not found, the page is launched without personalization. | DynamicsNAV://localhost/DynamicsNAV/CRONUS International Ltd./runpage?page=22&personalization=0000232e-0000-001a-0008-0000836bd2d2
Bookmark | Positions the cursor on a single record in a table. Only automatically generated bookmarks should be used. If you enter an incorrect bookmark, you will get an error message. | DynamicsNAV://localhost/DynamicsNAV/CRONUS International Ltd./runpage?page=22&bookmark=120000000089083237343
Mode | Enables you to open a page in a specific mode. Other modes include: view, edit, create, select, and delete. | DynamicsNAV://localhost/DynamicsNAV/CRONUS International Ltd./runpage?page=22&mode=View

Syntax for Creating Hyperlinks

The following table shows some examples of hyperlinks and provides information about how to specify parameters.

Parameters | Description | Syntax | Example
Company name | Enables you to switch a company (case sensitive). | DynamicsNAV:////<CompanyName>/RunPage?Page=<pageid> | Microsoft.Dynamics.Nav.Client.exe "DynamicsNAV:////CRONUS International Ltd./RunPage?Page=22"
Navigate | Enables users to send or save quick links to specific pages. | DynamicsNAV://///navigate?node=<service> | Microsoft.Dynamics.Nav.Client.exe DynamicsNAV://///navigate?node=Home/Items
RunPage | Enables you to run a specific page. | DynamicsNAV:////runpage?page=<page id> | DynamicsNAV:////runpage?page=42
RunReport | Enables you to run a specific report. | DynamicsNAV:////runreport?report=<report id> | DynamicsNAV:////runreport?report=50000
Server name | Enables you to switch servers. | DynamicsNAV://<ServerName>///RunPage?Page=<pageid> | Microsoft.Dynamics.Nav.Client.exe DynamicsNAV://MyServer///RunPage?Page=22
Server name optional port number | Enables you to specify an optional port number in the range 1-65535. The default port is 7046. | DynamicsNAV://<ServerName><:Port>///RunPage?Page=<pageid> | Microsoft.Dynamics.Nav.Client.exe DynamicsNAV://MyServer:1234///RunPage?Page=22
Service instance | Enables you to specify a Service instance. You can find this value in the CustomSettings.config file. | DynamicsNAV:///<Service>//RunPage?Page=<pageid> | Microsoft.Dynamics.Nav.Client.exe DynamicsNAV:///DynamicsNAV//RunPage?Page=22
Note Note

If you omit a parameter, such as Server or Service, do not remove the accompanying forward slash, as this will change the overall structure of the hyperlink.

Note Note

When you type a company name as a parameter, put the hyperlink in quotation marks if there are blank spaces in the name.

Running Hyperlinks

In Microsoft Dynamics NAV you can run hyperlinks in the following ways.

Method | To run a hyperlink
Run window | Click Start, and then click Run. Enter the hyperlink in the Run window and click OK.
Command Prompt tool | Open a Command Prompt tool and type the hyperlink directly into the tool.
Shortcut | Create a shortcut for the Microsoft Dynamics NAV executable on your Desktop. Right-click the shortcut, click Properties, and then enter the hyperlink URL into the Target field of the shortcut. Click OK, and then start Microsoft Dynamics NAV.
Browser window | Use a browser, such as Internet Explorer and type the hyperlink URL directly into the address bar. To type hyperlinks into a browser, you must have Microsoft Dynamics NAV installed on your computer.

See Also

Tasks

How to: Use a Shortcut to Run a Report

Concepts

Starting the RoleTailored Client from a Command Prompt


How to: Customize Data Displayed in a Drop-Down Control Using Field Groups

How to: Customize Data Displayed in a Drop-Down Control Using Field Groups
See Also

In the RoleTailored client, some fields are enabled with filter-as-you-type functionality. When you type text into these fields, a drop-down control appears that displays data from a source table. For example, in the sell-to-customer-no field on the Sales Orders page, records from the Customer table are displayed when you use this control.

If you do not define any field groups for the drop-down control, by default you only see data from two fields in the source table; the primary key and description fields, as these are indexed automatically.

To specify which fields are displayed in the drop-down control, you must use field groups. If you select the appropriate fields in the field groups table, you can help users to quickly find the data they need, without scrolling through multiple records. For example, if you define field groups on the Items table you can help the order processor to create new customer orders more easily. On the Sales Order card page, she can find specific items for the order, such as 2-inch nails, by using filter-as-you-type, and the drop-down control linked to the Items table. This could be very useful when creating a new customer order over the telephone.

Adding Fields to the Field Groups Table

You can add or remove field groups from the Field groups table, using the Classic client Table Designer.

To add fields to the field groups table

  1. In the Classic client, on the Tools menu, click Object Designer to open the Object Designer window.

  2. In Object Designer, click Tables, select a table, and then click Design to open Table Designer. For example, select table 18, the Customer table.

  3. To open the Field Groups table, select any row, click View, and then click Field Groups.

  4. Select the first row in the Field Groups table, and in the Name field, type DropDown.

  5. In the Groups field, click the AssistButton to open the Field List table.

  6. In the Field List table, make a selection from the fields in the source table. If you want to select more than one row, click on a row, and then use the SHIFT key to select multiple rows. Click OK to add the fields to the Field Groups table.

  7. Close the Field List table, and the Field Groups table. Click Save and Compile.

  8. Run the RoleTailored client to view your changes.

    For example, open the Edit Sales Order card page 1003, and then click Sell-to Customer No. The fields that you added to the Customer table, using field groups, are now displayed in the drop-down control for that field.

    Follow the same procedure to remove fields, or to change the order of fields displayed in the drop-down control.

See Also

Tasks

Walkthrough: Creating a Customer Card Page in Page Designer


Home Button Overview

Home Button Overview

The Home button is a default activity button in navigation pane of the RoleTailored client that displays items that link to List Places. The following figure shows an example of the Home button and its items. If you are running the CRONUS International Ltd. demo database, then you can see this example on page 9006, Order Processor Role Center.

Adding Items to the Home Button

There are two ways that you can add items to the Home button:

  • Add actions on the Role Center page.

    You use the Action Designer to add actions under the HomeItems control. You set up the actions to open list pages. Each action appears as an item under the Home button. For example, the following figure shows the Action Designer for the Home button items that are shown in the previous figure.

    For information about adding an action under the HomeItems control, see How to: Add Actions to a Page.

  • Add Cues on the Role Center page.

    Items from Cues are added to the Home Button automatically. When you add a cue, you set the DrillDownFormID Property to a list page for displaying the data. An item that links to the list page of the Cue automatically appears under the Home button. For more information, see Walkthrough: Creating a Cue on a Role Center.

Child Items

An item is placed as a child to another item automatically according to the following conditions:

  • The child item targets a list page that displays filtered data from a table.

  • The parent item targets the same list page as the child item, except that list page data is not filtered.

  • The parent item is defined by an action, not a Cue.

For example, in the figure at the beginning of this topic, the Sales Orders item opens a list page called Sales Order List. Its child items are defined by Cues that also open the Sales Order List page except that the data is filtered.

Customizing the Home Button from the RoleTailored Client

The Home button is always present in the navigation pane and cannot be removed. From the RoleTailored client, a user can hide or move items under the Home button that are created by actions. However, the user cannot remove items that are created from Cues.

See Also

Concepts

Creating Activity Buttons for the Navigation Pane


Creating Activity Buttons for the Navigation Pane

Creating Activity Buttons for the Navigation Pane

An activity button is a navigation pane button that displays links to additional list pages in the RoleTailored client. The Home and Departments activity buttons are default activity buttons on Role Centers. You can also create activity buttons to organize links to related pages and make it quicker for users to locate pages and minimize scrolling in the navigation pane.

The following figure illustrates a navigation pane that has the default activity buttons and two additional activity buttons: Posted Documents and Bank. The Posted Documents button is selected and shows actions that link to pages that are associated with posted documents.

Navigation pane clip that shows Activity buttons

When you create an activity button, you can apply one of the default images that are available for activity buttons. For more information, see How to: Add an Image to an Activity Button.

Note Note

You cannot set up an image on the page links of an activity button. All page links in the navigation pane use a default image that cannot be changed.

Setting up Activity Buttons and Page Links in the Navigation Pane

You use Action Designer to set up activity buttons on Role Center pages. The following figure illustrates the Action Designer setup for the Posted Documents button.

Action Designer that show Activity Button setup

The following guidelines apply when working with activity buttons:

  • Activity buttons are only valid on pages that have the type RoleCenter. For more information, see Walkthrough: Creating a Role Center.

  • All activity buttons are set up under a single action of the type ActionContainer and the subtype ActivityButtons. The container's location with respect to other action containers is not significant. Activity buttons are always displayed after the Home button in the navigation pane.

  • An activity button is defined by an action of the type ActionGroup that is indented once from the ActivityButtons row. The order of the activity buttons in the Action Designer determines the default order in the navigation pane.

  • Links to individual pages are defined by actions of the type Action that are indented once from the ActionGroup row. The order of the actions in the Action Designer determines the default order in the navigation pane.

See Also

Tasks

How to: Create an Activity Button and Page Links in the Navigation Pane
How to: Add an Image to an Activity Button
Walkthrough: Creating a Role Center


How to: Create an Activity Button and Page Links in the Navigation Pane

How to: Create an Activity Button and Page Links in the Navigation Pane
See Also

An activity button in the navigation pane displays a menu of links to additional pages in the RoleTailored client, as shown in the following example.

Navigation pane clip that shows Activity buttons

You create activity buttons and page links for the navigation pane by adding actions on the page that defines the Role Center. For more information, see Creating Activity Buttons for the Navigation Pane.

To create an activity button for the navigation pane

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, select the Role Center page, and then click Design.

  3. In Page Designer, select a blank row.

    You can find a blank row at the bottom of Page Designer. A blank rows gives you access to Action Designer for the page object instead of a single element.

  4. On the View menu, click Actions.

  5. In Action Designer, activity buttons are set up under a single action that has the Type set to ActionContainer and the SubType set to ActivityButtons. If this action already exists, then go to the next step. Otherwise, do the following to add the activity button container:

    1. Select a blank row.

      To insert a row above another row, right-click the row, and then click New.

      Note Note

      The location of the activity button container with respect to other containers is not important. However, if you are inserting a row, then insert the container at the end of the actions that belong to the container above.

    2. In the row, set Type to ActionContainer and SubType to ActivityButtons.

    3. Click on another row, and then click back on the row to fill in Name and Caption automatically.

  6. To add an activity button, select a blank row after the ActivityButtons container row.

    The order of the activity buttons in the Action Designer determines the default order in the navigation pane of the RoleTailored client. If there are existing activity buttons, then locate the new activity button where you want it now or you use the UP ARROW and DOWN ARROW keys to move it later.

  7. Set Type to ActionGroup.

  8. In the Caption field, type the text to display on the activity button in the RoleTailored client.

    Note Note

    You can also include an image on the activity button. For more information, see How to: Add an Image to an Activity Button

  9. Use the RIGHT ARROW and LEFT ARROW keys to indent the row one level from the ActivityButtons container row.

Note Note

If the RoleTailored client is currently open, you will not see your changes until you close and restart.

To add a page link to an activity button

  1. In Action Designer, select the action that defines the activity button to which you want to add the page link.

  2. On the View menu, click Properties.

  3. In the Properties window, set the RunObject property value to page name. Substitute name with either the page name or ID. For example, to link to the page with the ID 142 and name Posted Sales Shipments, you can type page 142 or page Posted Sales Shipments.

    Note Note

    Instead of typing page, you can just type p followed by the ID or name, such as p421 or pPosted Sales Shipments.

  4. Use the RIGHT ARROW and LEFT ARROW keys to indent the row one level from the ActionGroup row.

Note Note

If the RoleTailored client is currently open, you will not see your changes until you close and restart.

See Also

Tasks

Walkthrough: Creating a Role Center

Concepts

Creating Activity Buttons for the Navigation Pane
Adding Actions to Pages
Creating and Maintaining Pages


How to: Add an Image to an Activity Button

How to: Add an Image to an Activity Button

The RoleTailored client includes images that you can use on activity buttons in the navigation pane. Images are displayed on the left side of activity buttons, as shown in the following navigation pane example.

Navigation pane clip that shows Activity buttons

To add an image on an activity button, you must provide the name of the image. For a list of images and their names, see Activity Button Image Library.

Note Note

You cannot set up an image on the page links of an activity button. All page links in the navigation pane use a default image that cannot be changed.

You set up activity buttons the page that is used as the Role Center. To complete this procedure, you must have the name or ID of the Role Center page.

To set up image on an activity button

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, select the Role Center page, and then click Design.

  3. In Page Designer, select a blank row.

    You can find a blank row at the bottom of Page Designer. A blank rows gives you access to Action Designer for the page object instead of a single element.

  4. On the View menu, click Actions.

  5. In Action Designer, locate the action that has the Type set to ActionContainer and the SubType set to ActivityButtons.

    This defines the activity button container.

  6. Select the ActionGroup row for the activity button on which you want the image. Activity buttons are defined by the actions that have the Type set to ActionGroup.

  7. On the View menu, click Properties.

  8. In the Properties window, in the Value field for the Image property, type the name of the image that is found in the activity button image library. For more information, see Activity Button Image Library.

Note Note

If the RoleTailored client is currently open, you will not see your changes until you close and restart.

See Also

Tasks

How to: Create an Activity Button and Page Links in the Navigation Pane

Concepts

Activity Button Image Library


Activity Button Image Library

Activity Button Image Library

The RoleTailored client includes images that you can use on activity buttons in the navigation pane. To add an image to an activity button, you must provide the name of the image. For more information, see How to: Add an Image to an Activity Button.

Activity Button Images

You can use the following images for activity buttons.

A list of Activity Button images and their names

See Also

Tasks

How to: Add an Image to an Activity Button
How to: Create an Activity Button and Page Links in the Navigation Pane

Concepts

Creating Activity Buttons for the Navigation Pane


Including Microsoft Dynamics Online Connect on Role Centers

Including Microsoft Dynamics Online Connect on Role Centers

For Microsoft Dynamics NAV 2009 SP1, the RoleTailored client includes a control add-in that that you can use on Role Centers to display role-based content from Microsoft Dynamics Online Connect. Connect is a Web service that distributes Microsoft Dynamics product and business information from sources such as CustomerSource and the Microsoft Dynamics community. The information that Connect provides on a Role Center is based on the Role Center's profile or a profile that the Role Center user chooses. If the content is available in different languages, then content is displayed in the language that matches language that is defined for the Role Center user.

To set up a Role Center with Connect, you create a card part page that contains the Connect control add-in and then use the card part page on the Role Center. For more information, How to: Include Microsoft Dynamics Online Connect on Role Centers.

If you have installed the Microsoft Dynamics NAV demo database, then Connect is already added by default on several Role Centers.

Supported Profiles and Default Role Centers

The following table lists the Role Center profiles that are supported by Connect and the Role Centers that use the profiles by default when you install the Microsoft Dynamics NAV demo database.

Note Note

Whether the Connect part is visible on a Role Center is specified by the Visible Property of the Role Center page.

Role Center ID | Profile ID | Visible by default
9000 | Shipping and Receiving - WMS | no
9001 | Accounting Manager | yes
9002 | Accounts Payable Coordinator | no
9003 | Accounts Receivable Administrator | no
9004 | Bookkeeper | no
9005 | Sales Manager | yes
9006 | Order Processor | no
9007 | Purchasing Agent | no
9008 | Shipping and Receiving | no
9010 | Production Planner | yes
9011 | Shop Supervisor - Foundation | no
9012 | Shop Supervisor | no
9014 | Resource Manager | yes
9015 | Project Planner | yes
9016 | Dispatcher | no
9018 | IT Manager | yes
9019 | President | yes
9020 | President - Small Business | yes

User Personalization of Connect

If a Role Center is set up with Connect, then a user has the following options to personalize the Role Center:

  • Show or hide the page part that contains Connect.

    The user can do this by clicking the Customize button in the Role Center. For more information, see the Microsoft Dynamics NAV Help from the RoleTailored client.

  • Change the profile that is used by Connect.

    The user changes the profile from within the Connect content. The profile that the use selects overrides the profile that is assigned to the Role Center.

  • Sign in to Windows Live™.

    When a user signs in to Windows Live, additional content is available that is based on the user's CustomerSource account.

Information Sent from the Role Center to Connect

When a Role Center opens, the Connect control add-in sends the following information about the Microsoft Dynamics NAV software over the Internet to Microsoft:

  • Product name

  • Product version

  • Some license information, but not the license number

  • Country/region version

  • Language

  • Profile, which is based on the Role Center ID

Internet Access and Security

If you make Connect available to users, then they will require Internet access to use the service. If you have not previously offered Internet access to users, then you should consider the security implications before implementing Connect. For more information, see Microsoft Dynamics Online Connect.

See Also

Tasks

How to: Include Microsoft Dynamics Online Connect on Role Centers

Concepts

Installing and Configuring RoleTailored Client Control Add-ins on Pages


How to: Include Microsoft Dynamics Online Connect on Role Centers

How to: Include Microsoft Dynamics Online Connect on Role Centers
See Also

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

The RoleTailored client installation includes a control add-in that you can use on Role Centers to connect to and display information from Microsoft Dynamics Online Connect. The information from Connect is based on the Role Center's profile. The Connect control add-in is provided in the Microsoft.Dynamics.NAV.Client.DynamicsOnlineConnect.dll assembly file. By default, the assembly is installed on the computer running the RoleTailored client in the C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-ins\Connect folder. Setting up the control add-in for Connect is similar to other control add-ins. For more information, see Installing and Configuring RoleTailored Client Control Add-ins on Pages and Including Microsoft Dynamics Online Connect on Role Centers.

Note Note

If you make Connect available to users, then they will require Internet access to use the service. If you have not previously offered Internet access to users, then you should consider the security implications before implementing Connect. For more information, see Microsoft Dynamics Online Connect.

Setting up Connect with the Demo Database Installed

If you installed the Microsoft Dynamics NAV demo database, then the Connect control add-in is set up by default on several Role Centers that use the profiles that are supported by Connect. To see a list of the profiles and the associated Role Centers, see Including Microsoft Dynamics Online Connect on Role Centers.

The demo database contains the page 9175 Connect, which hosts the Connect control add-in. You use this page to set up Connect on your own Role Centers as described in the following procedure.

To set up a Connect on a Role Center with the demo database installed

  1. Create the Role Center page that has a part that targets the page 9175 Connect.

    For more information, see Walkthrough: Creating a Role Center.

  2. Assign the Role Center to a profile that is supported by Connect.

    Note Note

    You can also use a profile that is not supported by Connect. In this case, when the Role Center opens, the user is prompted to choose a supported profile.

Setting up Connect Without the Demo Database Installed

Use the procedure in this section to set up Role Centers with Connect if you have not installed the demo database.

To set up Connect on a Role Center without the demo database installed

  1. Register the Connect control add-in in the Client add-in table of the Microsoft Dynamics NAV database. You must provide the following information:

    • Control add-in name - Microsoft.Dynamics.NAV.MicrosoftDynamicsOnlineConnectControl

    • Public token key - 31bf3856ad364e35

    For more information, see How to: Register a RoleTailored Client Control Add-in.

  2. Use the Connect control add-in on a page.

    For more information, see How to: Set up a RoleTailored Client Control Add-in on a Page.

  3. Create the Role Center page and include a part that uses the Connect page from step 2.

    For more information, see Walkthrough: Creating a Role Center.

  4. Define the Role Center profile that is supported by Connect and assign it your Role Center.

    For more information, see How to: Create a Profile.

    Note Note

    You can also use a profile that is not supported by Connect. In this case, when the Role Center opens, the user is prompted to choose a supported profile.

See Also

Concepts

Including Microsoft Dynamics Online Connect on Role Centers
Installing and Configuring RoleTailored Client Control Add-ins on Pages


How to: Style Field Text on a Page

How to: Style Field Text on a Page

A page field control includes the Style Property that you use to format the text that displays in a page field. The Style property has four values that apply different formats to field text. The format that is applied to a field in Edit mode is different than the format that is applied in View mode. The following table describes the four values and the corresponding format in Edit and View modes.

Value | Format in Edit mode | Format in View mode
Strong | Bold | Bold
Attention | Red | Default
Favorable | Bold + Green | Bold
Unfavorable | Bold + Italic + Red | Bold + Italic

By using the field's StyleExpr Property, you can apply the formatting to the field at all times or based on the field's data.

Always Applying a Format to Text in a Page Field

Use the following procedure to apply formatting to field text on a page at all times.

To format field text always

  1. Open the page in Page Designer.

  2. Select the field that you want to format, and on the View menu, click Properties.

  3. Set the Style property value to one of the formats that are described in the preceding table.

  4. Set the StyleExpr property value to true.

Applying a Format to Text in a Page Field That Is Based on the Field's Data

By using a page field's StyleExpr property, you can apply the format that is specified by the Style property to a field based on the field's data. For example, you can display text in red if the value of the field is a negative number, italic red if an item is low in stock, or bold green to indicate a favorable value, such as a high credit limit.

To set up this formatting, you define a Boolean variable and add C/AL code to the page that evaluates the field's data. The C/AL code should return the Boolean variable as True when the data meets the conditions for which you want to apply the formatting. You then set the variable on the field's StyleExpr property.

To define the variable to use to format field text

  1. Open the page in Page Designer.

  2. On the View menu, click C/AL Globals.

  3. Define the variable, and then set the DataType to Boolean.

  4. On the View menu, click Properties to open the variable's properties, and then set the IncludeInDataSet to Yes.

    Note Note

    If the IncludeInDataSet Property is not set to Yes, then when you run the page, you will receive an error that states that the identifier variable could not be found.

  5. On the View menu, click C/AL Code, and then add C/AL code that sets the variable.

    Note Note

    The variable must evaluate to true.

To set the variable to the StyleExpr property of the page field

  1. In Page Designer, open the Properties of the field that you want formatted.

  2. Set the Style property value to one of the formats that are described at the beginning of this topic.

  3. Set the StyleExpr property value to the variable that you defined in the previous procedure.

See Also

Reference

Style Property
StyleExpr Property
IncludeInDataSet Property


Arranging Fields in Rows and Columns Using a FixedLayout Control

Arranging Fields in Rows and Columns Using a FixedLayout Control
See Also

This topic describes the layout and behavior of fields in a FixedLayout control on a page. You use the FixedLayout control to arrange page fields in rows and columns, similar to a matrix, except that the FixedLayout control contains a specific number of fields, and a matrix can contain an unspecified number of fields. You typically use the FixedLayout control to display statistical data in a FastTab on a page or information in the details section of a Worksheet page. If you are using the Microsoft Dynamics NAV demo database, then you can see examples of these uses in page 151, Customer Statistics, and page 40, Item Journal.

General

In Page Designer, you include a FixedLayout control under a group control. You can add fields directly under the FixedLayout control as shown in the following Page Designer example that contains four fields.

The following figure illustrates the resulting field layout on a page.

It is important to notice that there are no captions for the fields.

Grouping Fields in a Fixed Layout Control

By placing the fields in a FixedLayout control within a group control, you can define separate rows and columns to create a matrix-like arrangement. The following figure shows a Page Designer example that places four fields of the FixedLayout control within a group control.

The following figure illustrates the resulting field layout on a page.

The group control caption appears as the column header, and the field control captions appear as the row headers. If you add two more group controls containing fields, then the layout on the page will look similar to the following figure:

Only the field captions for the first group control appear. The field captions in other group controls are ignored.

Multiple Fixed Layouts

You can also set up more than one FixedLayout control within a group control. For example, the following figure illustrates the page layout if you had four FixedLayout controls:

The page area is divided into two columns that contain the separate FixedLayout fields.

Note Note

The fields in the FixedLayout controls in the figure are not within a group control. If they were within a group control, then they would follow the same principle as described in the previous section about grouping fields.

Editing Fields in a Fixed Layout

Fields in a fixed layout are not editable even if the Editable Property property is set to TRUE. However, if the field drills down to a page where the field source is defined, then you can edit the field.

See Also

Tasks

How to: Arrange Page Fields in Rows and Columns Using a FixedLayout Control


How to: Arrange Page Fields in Rows and Columns Using a FixedLayout Control

How to: Arrange Page Fields in Rows and Columns Using a FixedLayout Control
See Also

This topic describes how to use a FixedLayout group control on a page to arrange page fields in rows and columns, similar to a matrix. A FixedLayout group control is typically used to display statistical data, as shown in the following figure of an example page that shows sales totals for different time periods.

Fields in a FixedLayout group control are displayed in a FastTab with a heading for each row and column. For more details about the FixedLayout group control, see Arranging Fields in Rows and Columns Using a FixedLayout Control.

To arrange page fields in rows and columns

  1. Open the page in Page Designer.

  2. In Page Designer, insert a blank line where you want to locate the fields.

  3. Set the Type and SubType field to Group. In the Caption field, type the text that you want as the heading of the FastTab that contains the fields.

  4. On the next line, set the Type to Group and SubType field to FixedLayout.

  5. On the next line, set the Type and SubType field to Group. This defines the placeholder for the first column of fields. To add a heading to the column, type the text in the Caption field.

  6. On the next line, set the Type to Field. This defines the first field in the column. In the Caption field, type the text that you want as heading for the row.

  7. Specify the data source for the field by doing one of the following:

    • If the data source is a field of a the table that is associated with the page, then on the View menu, click Field Menu, select the field, and then click OK.

    • If the data source is a variable, then on the View menu, click C/AL Globals or C/AL Locals, and then create the variable. After you create the variable, in the SourceExpr field in Page Designer, click the Assist button and select the variable.

  8. Repeat steps 6 and 7 to add the remaining fields in the first column.

    The following figure shows a Page Designer example that has four fields.

  9. Repeat steps 5 through 8 to add group controls that define the remaining columns.

    Note Note

    You do not need to specify captions for these fields. Only the captions of fields in the first column define the row headings.

See Also

Concepts

Arranging Fields in Rows and Columns Using a FixedLayout Control


Page Designer Troubleshooting

Page Designer Troubleshooting

This topic contains information about known troubleshooting issues in Page Designer.

Expand image OK and Cancel Button Unavailable in the Field Menu Window

The Field Menu window enables you to add fields and source expressions to a page. There are two ways in which you can use the Field Menu window:

  1. You can select a row of Type Field, click View, and then click Field Menu. Choose the field or fields that you want to be a source expression for the field and click OK or Apply. You will see a message box asking, “Do you want to add the fields that are selected in the field menu?”

  2. You can open the Field Menu window, select the fields that you want to add, and then select the row in the page where you want to insert fields. If you choose this method, the OK and Cancel buttons are unavailable in the Field Menu window. If you click anywhere in the Page Designer window, you will see a message box asking, “Do you want to add the fields that are selected in the field menu?”

Expand image See Also

Concepts

Creating and Maintaining Pages


Page Designer Walkthroughs

Page Designer Walkthroughs

The walkthroughs in this section provide step-by-step instructions on how to create pages for the RoleTailored client. Each walkthrough presents a different scenario intended to help you understand how different page types can be used to build a selection of page objects.

Pages are XML based, making the Page Designer fundamentally different from the Form Designer. Pages require less design considerations and more understanding of how XML elements work together. In these walkthroughs you will see how page parts and controls can be arranged in the Page Designer window to create a hierarchy of XML elements that result in pages.

Page controls contain properties, triggers, functions, and code units in just the same way as forms but for the purposes of these walkthroughs, creating the basic structure of the page is the focus, not how to add code units or triggers. For more detailed information about these issues, see the appropriate section in the Microsoft Dynamics NAV 2009 Developer Help.

In This Section

Walkthrough: Creating a Customer Card Page in Page Designer

Walkthrough: Creating a Customer List in Page Designer

Walkthrough: Adding Actions to a Customer List Page

Walkthrough: Adding a FactBox to the Customer List Page

Walkthrough: Creating a Role Center

Walkthrough: Creating a Wizard Page

Walkthrough: Creating a Document Page

Walkthrough: Creating a Worksheet Page

Walkthrough: Creating a Cue on a Role Center

See Also

Concepts

Pages Overview
Adding Actions to Pages


Walkthrough: Creating a Customer Card Page in Page Designer

Walkthrough: Creating a Customer Card Page in Page Designer

In this walkthrough, you learn how to create a card page to display customer details. A card page is used to display more detailed information than is available on a list page. You can link a list page to a card page so that when you select a customer in the list, you open a specific customer card page.

Expand image About This Walkthrough

This walkthrough provides an overview of how to create a card page in Page Designer, how to add controls, and how to preview the page in the RoleTailored client.

This walkthrough illustrates the following tasks:

  • Creating a card page

  • Adding controls

  • Saving the page

  • Promoting customer data to the FastTab header

  • Adding a FactBox to a card page

  • Running the page

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license.

Expand image Story

Simon is a partner working for CRONUS International Ltd. Kevin, the Sales Manager has asked Simon to create a card page to store customer information. He wants to be able to view the details of each customer in a card page when he clicks on a customer in the customer list.

Expand image Creating a Card Page

To create a customer card page to run on the RoleTailored client, Simon knows that he must use the Classic client Object Designer.

Note Note

In this walkthrough, to learn about the properties and controls of a card page, you will create a card page from a blank page. If you are running Microsoft Dynamics NAV 2009 SP1, Object Designer also includes a wizard that you can use to create a card page that sets up many properties and controls for you. For more information about the wizard, see How to: Create a Page.

To create a card page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. In the Table text box, click the AssistButton, select the Customer table, and then click OK.

  4. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  5. On the View menu, click Properties.

  6. Close the Properties dialog box.

  7. Locate the PageType property, and then set the Value field to the page type Card.

  8. In the Name field of the first row, which has the type Container and the subtype ContentArea, type CustomerCardContainer.

You have now successfully created a card page. However, you cannot save your card page until you have added at least one control to your page.

Expand image Adding a Control to Display Customer Details

Simon wants to add a basic control to his card page to display a selection of fields from the customer table in a group that can be expanded or collapsed. He knows that all card pages use the FastTab control to display data in this way, so he decides to add a FastTab control to his blank card page.

To add a control to display customer details

  1. On your blank card page in Page Designer, click the first available row. Type the name, CustomerCardContainer, in the Name field. Click the second row and then click the first row. The other fields are completed automatically. By default, Type is set to Container and SubType is set to ContentArea.

  2. In the second row, type the name CustomerCardGroup in the Name field and in the Caption field type General. Set Type to Group and SubType to Group.

  3. In the third row, set Type to Field. On the View menu, click Field Menu.

    In the Field Menu window, select fields from the Customer table.

    Select multiple fields by holding down the SHIFT key while you select the following rows:

    • No.

    • Name

    • Search Name

    • Name 2

    • Address

    • Address 2

    • City

    • Contact

    • Phone No.

  4. Click OK. A message box appears with the following message: "Do you want to add the fields that are selected in the field menu?" Click Yes.

    If the OK and Cancel buttons are unavailable, see Page Designer Troubleshooting for more information.

    In page designer, your card page should now look something like the following.

  5. Select the next available blank row on your page, below Phone No. Click the View Menu and click Properties. In the Properties window, type the name Kevin's Customer Card in the Caption and CaptionML fields.

  6. Close the Properties window.

Expand image Saving the Page

Simon thinks it would be a good idea to save the page before making any further changes.

To save the page

  1. When you close the Page Designer window, the Save As dialog is displayed.

  2. Choose an ID number for your page in the 50000 range. For this walkthrough, type 50002 in the ID field and Kevin's Customer Card in the Name field.

  3. Leave the Compiled check box selected and click OK.

    Note You can clear the Compiled check box to save your page, but your page will not run. You can only compile if there are no errors on the page.

Expand image Promoting Customer Data to the FastTab Header

Now Simon wants to highlight key customer information on his customer card page. He can do this by making the contents of some fields visible on the FastTab header, even when a FastTab is in its collapsed state.

To promote key customer data to the FastTab header

  1. Open Object Designer.

  2. Open Kevin's Customer Card page 50002.

  3. In Page Designer, select a single field in one of the FastTab groups. For example, in the General group select Contact.

  4. With this row selected in page designer, click View, and then click Properties.

  5. In the Properties window, select the Importance property.

  6. The Importance property has three possible states available in the drop-down:

    • Standard

    • Promoted

    • Additional

    Select Promoted.

  7. Close the Properties window and the Page Designer. The Save Changes dialog is displayed.

  8. Click Yes in the Save Changes dialog box to save and compile Kevin's Customer Card page.

You have now successfully promoted Contact to the FastTab Header.

Expand image Running the Page

Test your new card page by running the RoleTailored client.

To run the page

  • In Object Designer, select page 50002, and then click Run.

    The RoleTailored client opens and displays the new card page.

Expand image Next Steps

Simon wants to create a customer list page for his customers and to create a link from the list page to Kevin's Customer Card page.

Expand image See Also

Tasks

Walkthrough: Creating a Customer List in Page Designer
How to: Create a FactBox to Display Customer Data
How to: Add FastTabs to a Customer Card Page
Page Designer Troubleshooting
How to: Create a Page
Touring the RoleTailored Client Pages
How to: Run a Page


Walkthrough: Creating a Customer List in Page Designer

Walkthrough: Creating a Customer List in Page Designer

In this walkthrough, you will learn how to create a basic page that displays a list of customers. From a selection in the customer list, you will enable end users to access customer details from the customer card.

Pages are a new type of object in Microsoft Dynamics NAV 2009. They are used in the same way that forms are used in earlier versions. Unlike forms, pages can be displayed on multiple clients, including the RoleTailored client, which is a Windows client. This flexibility lets you display the same information in different clients. Pages cannot be viewed in the Classic client.

Expand image About this Walkthrough

This walkthrough provides an overview of how to create and run a simple list page in Microsoft Dynamics NAV 2009, and demonstrates how to:

  • Create a list page.

  • Associate an existing card page with selections in the list.

  • Add controls to the page to display specific fields from a table.

  • Save the page.

  • Run the page in the RoleTailored client.

Prerequisites

The following prerequisites are required for this walkthrough:

  • Microsoft Dynamics NAV 2009 installed with a developer license.

Expand image Story

Simon is a partner working for CRONUS International Ltd. Kevin, the Sales Manager at CRONUS, has contacted Simon and asked him to create a customer list. Kevin would like Simon to be sure that the existing customer card displays when he double-clicks a customer in the list.

Expand image Creating a List Page

To create Kevin's customer list, Simon knows that he needs to create a list page. Simon also needs to ensure that the card for a specific customer will open when Kevin double-clicks a customer in the list.

Note Note

In this walkthrough, to learn about the properties and controls of a list page, you will create a list page from a blank page. If you are running Microsoft Dynamics NAV 2009 SP1, Object Designer also includes a wizard that you can use to create a list page that sets up many properties and controls for you. For more information about the wizard, see How to: Create a Page.

To create a List page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. In the Table text box, click the AssistButton, select the Customer table, and then click OK.

  4. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  5. In the Name field of the first row, which has the type Container and the subtype ContentArea, type CustomerListContainer.

  6. Select a blank row, and on the View menu, click Properties.

  7. Locate the PageType property, and then set the Value field to the page type List.

  8. In Page Designer, from the View menu, click Properties.

    The Properties window opens.

  9. Locate the CardFormID property and click the AssistButton in the value field.

    The Page List window opens.

  10. Click page 21 Customer Card and then click OK.

    Note Note

    In Microsoft Dynamics NAV 2009, the CardFormID Property is used to associate an item in a list with a specific, existing card page. In this walkthrough, the Customer card page is associated with the Customer list page, enabling users to launch the customer card when they double-click a customer from the list.

  11. Close the Properties dialog box.

Expand image Adding Customer Information to the Page

Now that Simon has created a basic list page, he wants to add a control and the appropriate fields so that the page will display the number, name, address, city, and phone number for each customer in the list.

To add controls to the page

  1. In Page Designer, click the Name column in the second row and type CustomerListGroup. Set Type to Group and set SubType to Repeater.

    Note Note

    The CustomerListGroup is indented one level below the CustomerListContainer, indicating that it is a child of, and will be displayed within, the CustomerListContainer.

  2. Select the third row.

  3. On the View menu, click Field Menu.

    The Field Menu window opens, displaying the list of available fields from the Customer table (Table 18).

  4. Select multiple fields by holding down the CTRL key while you click the following rows:

    • No.

    • Name

    • Address

    • City

    • Phone No.

  5. Click in Page Designer.

    A message box appears with the following message: "Do you want to add the fields that are selected in the field menu?".

    Note Note

    The OK button in the Field Menu dialog box is disabled and the field changes can only be committed by clicking in Page Designer. This is expected behavior.

  6. Click Yes.

    The customer list displays, as shown in the following screen shot

Expand image Saving and Running the Page

Now that Simon's page is complete, he wants to see how it looks. Eventually, he will add an action to another page so Kevin can access the page. But while he is still working on it, Simon can save the page and then quickly run it in the RoleTailored client using the following procedure.

To save and run the page

  1. Press CTRL+S.

    The Save As dialog box appears.

  2. Under ID, enter 50000.

  3. Under Name, enter Kevin's Customer List.

  4. Click OK.

    This name is displayed in the page's action pane.

  5. To run the page, in Page Designer, select the page 5000 Kevin's Customer List, and then click Run.

    The RoleTailored client opens and displays the new page.

Expand image Next Steps

Next, Simon needs to add actions to the customer list page. He looks at the customer list that he created earlier and decides that he wants to add a Sales Order action. When selected, this action will create a new sales order.

Expand image See Also

Tasks

Walkthrough: Adding Actions to a Customer List Page
Walkthrough: Adding a FactBox to the Customer List Page
How to: Create a Page
Touring the RoleTailored Client Pages
How to: Run a Page


Walkthrough: Adding Actions to a Customer List Page

Walkthrough: Adding Actions to a Customer List Page

In this walkthrough, you will learn how to add a new Action menu item and then display that item as an icon on the Action Pane. The Action Pane is located at the top of most pages and is used to provide end users with easy access to common or important actions. Action menu items are referred to as actions. Actions that are displayed on the Action pane are referred to as promoted actions.

Expand image About this Walkthrough

This walkthrough provides an overview of how to create and run a simple list page in Microsoft Dynamics NAV 2009, and demonstrates how to:

  • Add an action to the customer list page to create a new sales order.

  • Display the Sales Order action on the Actions menu.

  • Promote the Sales Order action so it is displayed in the Action pane.

  • Modify the Sales Order action so it creates a new sales order for the customer currently selected in the customer list.

Prerequisites

This walkthrough builds on the steps described in Walkthrough: Creating a Customer List in Page Designer.

Expand image Story

Simon shows the customer list page that he created to Kevin, the Sales Manager at CRONUS International Ltd. who contracted him to create this page. Kevin likes how the customer list looks, but he would like Simon to add a menu item on the Actions menu to create a new sales order for the currently selected customer.

Expand image Adding an Action to the Customer List

Simon looks at the customer list that he created earlier and adds a new action to the page to create a sales order.

To add an action to the customer list page

  1. In the Classic client, click Tools, and then click Object Designer.

  2. In Object Designer, click Page, select page 50000 Kevin's Customer List, and then click Design.

    The Kevin's Customer List page opens in Page Designer.

  3. Select the first empty line on the page, which is located immediately below the <Phone No.> field.

  4. With this line selected, on the View menu, click Actions.

    Action Designer opens. For this walkthrough, Action Designer will be used to set actions on the page.

  5. In Action Designer, click the Name column in the first row and type CustomerListActions.

    The relevant ActionContainers for a list page are:

    • NewDocumentItems

    • ActionItems

    • RelatedInformation

    • Reports

    • HomeItems

    • ActivityButtons

    For more information about the different types of actions, see Actions Overview.

  6. Set the SubType to a value of ActionItems.

    Actions with a SubType of ActionItems are displayed on the Action menu just above the Place section.

  7. Click the Caption column in the second row and type Sales Order.

  8. Set the Type to Action.

  9. Click the third row and then click the second row. The remaining action columns are automatically filled in.

    This action is indented one level below the ActionContainer to indicate that it is a child of (contained by) the ActionContainer.

  10. Open the Properties window.

  11. Set the RunObject property to Page Sales Order.

  12. Save the page.

  13. To run the page, in Page Designer, select the page 5000 Kevin's Customer List, and then click Run.

    The Sales Order action now displays in the Actions menu.

Expand image Promoting an Action

When Simon opens the page, he realizes that he would like to promote the Sales Order action so that it displays on the Action pane in the New category. Promoted actions are displayed as icons within the Action pane located at the top of the page.

To promote an action

  1. With the first empty line selected in Page Designer, open Action Designer.

  2. Select the Sales Order action and view the Properties window.

  3. Set the Image property to Document.

  4. Set the Promoted property to Yes.

  5. Set PromotedCategory property to New.

  6. Set PromotedIsBig property to Yes.

  7. Set the Caption property to S&ales Order.

    The ampersand identifies the access key for this menu item. The access key is automatically set to the first letter in the caption by the client if another access key is not set using the ampersand.

  8. Save the page.

  9. Run the page.

    The Sales Order command is now displayed in the Action Pane, as shown in the following screen shot.

Expand image Linking an Action with a Specific Item in a List

Simon verifies that the Sales Order action now displays in the Action pane. However, when he selects the Sales Order action, the Sales Order card opens and displays the first sales order in the database. Simon remembers that Kevin asked him to have the Sales Order action open a new sales order for the currently selected customer, instead. Simon opens the customer list page and starts making this change.

To add an action

  1. In Action Designer, select the Sales Order action and view the Properties window.

  2. Set the RunFormMode property to Create.

    The default value for this property is Edit. By setting this property to a value of Create, a sales order page will open in create mode, enabling the end user to create a new sales order.

  3. Set the RunFormLink property value to Sell-to Customer No.=FIELD(No.) using the following steps:

    1. In the RunFormLink property value, click the Assist-Edit button (ellipsis).

      The Table Filter window appears.

    2. Click the AssistButton in the Field cell, click Sell-to Customer No., and then click OK.

    3. Click the drop-down list box in the Type cell and then click FIELD.

    4. Click the AssistButton in the Value cell, click No., and then click OK.

    5. Click OK.

      The customer number in the customer list is now linked to the Sell-to Customer number in the sales order. This means that when the Sales Order action is clicked, a new sales order will be created for the customer that is currently selected in the customer list.

  4. Save the page.

  5. Run the page.

    To test the new functionality, select a customer from the list and then click the Sales Order action. A new sales order appears. Press the TAB key twice, or click any field on the page for customer information to populate the fields.

Expand image Next Steps

Next, Simon will add a FactBox to the customer list page. Simon will use this FactBox to display additional information about the currently selected customer in the list.

Expand image See Also

Tasks

Walkthrough: Adding a FactBox to the Customer List Page
Walkthrough: Creating a Customer List in Page Designer


Walkthrough: Adding a FactBox to the Customer List Page

Walkthrough: Adding a FactBox to the Customer List Page

In this walkthrough, you will learn how to add a FactBox to the customer list page and use it to display credit information about the selected customer. FactBoxes are pages that you can create and then use within another page to display targeted, related information about a selection.

Expand image About this Walkthrough

This walkthrough provides an overview of how to add a FactBox to another page in Microsoft Dynamics NAV 2009, and demonstrates how to:

  • Create a FactBox page.

  • Add fields to the FactBox.

  • Add the FactBox to the customer list page.

  • Associate the selection in the customer list with the information displayed in the FactBox.

Prerequisites

This walkthrough builds on the steps described in Walkthrough: Creating a Customer List in Page Designer and Walkthrough: Adding Actions to a Customer List Page.

Expand image Story

Kevin reviews the customer list page that Simon has created and has one last request. Kevin decides that he would like to display the credit limit and other relevant information for each customer when selected.

Expand image Creating a FactBox

Simon knows that he can use a FactBox to display the type of information Kevin is asking for on the customer list page. Simon creates a new FactBox page based on card part page type. He associates the page with the customer table and then adds the Credit Limit (LCY), Payment Terms Code, and Blocked fields to the FactBox.

Note Note

In this walkthrough, to learn about the properties and controls of FactBox, you will create a card part page from a blank page. If you are running Microsoft Dynamics NAV 2009 SP1, Object Designer also includes a wizard that you can use to create a card part page that sets up many properties and controls for you. For more information about the wizard, see How to: Create a Page.

To create a FactBox to display credit information

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. In the Table text box, click the AssistButton, select the table 18 Customer, and then click OK.

  4. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  5. On the View menu, click Properties.

  6. Locate the PageType property, and then set the Value field to the page type CardPart.

  7. Close the Properties window.

  8. In the Name field of the first row, which has the type Container and the subtype ContentArea, type CustomerListFactBoxContainer.

  9. Select the second row.

  10. On the View menu, click Field Menu.

  11. Select multiple fields by holding down the CTRL key while you click the following fields:

    • Credit Limit (LCY)

    • Payment Terms Code

    • Blocked

  12. Click outside the Field Menu window.

    A message box appears with the following message: "Do you want to add the fields that are selected in the field menu?".

  13. Click Yes.

  14. Close the Field Menu window.

  15. Press CTRL+S to save the FactBox page.

    The Save As dialog box appears.

  16. Specify an ID of 50001 and a Name of Kevin's Customer List Fact Box. Click OK.

  17. To run the page, in Page Designer, select the page and click Run.

    The RoleTailored client opens and displays the new FactBox page

Expand image Adding a FactBox to the Customer List Page

Simon is now ready to add the FactBox to the customer list page that he created earlier. To do this, he first needs to open the customer list page in Page Designer and then add the FactBox to the bottom of the customer list page.

To add a FactBox to the customer list page

  1. In Object Designer, click Page, select page 50000 Kevin's Customer List, and then click Design.

    The Kevin's Customer List page opens in Page Designer.

  2. Select the first empty line on the page, which is located immediately below the <Phone No.> field.

  3. Click the Name column and type FactBoxArea. Set Type to Container and set SubType to FactBoxArea.

  4. Select the FactBoxArea line and click the left arrow twice to negative indent this row until it is at the same level as the CustomerListContainer.

  5. Click the next empty line in Page Designer and set the Type to a value of Part.

  6. Open the Properties window.

  7. Set the PagePartID property to Kevin's Customer List Fact Box by entering 50001 for the property value.

  8. Set the SubFormLink property to No.=FIELD(No.).

    Note Note

    The PagePartID property must be set before the SubFormLink property.

  9. Save the page.

  10. Run the page. The FactBox is displayed, as shown in the following screen shot.

Expand image See Also

Tasks

Walkthrough: Creating a Customer List in Page Designer
Walkthrough: Adding Actions to a Customer List Page
How to: Create a Page
Touring the RoleTailored Client Pages
How to: Run a Page


Walkthrough: Creating a Role Center

Walkthrough: Creating a Role Center

In this walkthrough, you will learn how to create a new Role Center for the RoleTailored client. In Microsoft Dynamics NAV 2009, a Role Center is a type of page on which you can place different parts. Each part is a container in which you can host other pages or pre-defined system parts, such as an Outlook part or parts for adding tasks, notifications, or notes.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating a Role Center page.

  • Creating a card part page that displays a visual representation of work queues.

  • Adding actions to the card part page.

  • Adding the card part page to the Role Center page.

  • Adding the MyNotes system part to the Role Center page.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license.

Expand image Story

Simon is a partner working for CRONUS International Ltd. Susan, the Order Processor at CRONUS, has contacted Simon and asked him to create her a new Role Center that will show her work queue, give her easy access to common actions like creating a new sales order, and will also display a list of current notifications.

Expand image Creating a Role Center Page

Simon creates a new Role Center using Page Designer. Simon knows that because Role Centers can contain several different parts, they are not tied to a specific source table. As a result, when Simon creates the Role Center page, he does not select a table in the New Page dialog box.

To create a Role Center page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  4. In the Name field of the first row, which has the type Container and the subtype ContentArea, type RoleCenterContainer.

  5. Select a blank row, and on the View menu, click Properties.

  6. Locate the PageType property, and then set the Value field to the page type RoleCenter.

  7. Close the Properties window.

  8. Save the page and name it Sales Order Proc. Role Center. Set the ID to 50005.

Expand image Creating a Sales Order Processor Queue Page

Simon needs to create a page that provides a visual indicator of the work Susan has to do each day. He wants to host this page in a part on Susan's Role Center so he will need to create it before he can add it to the Role Center page that he just created. He has already created a table that contains the fields that he wants to use, so he only needs to create the page. Simon knows that to create a queue, he must use the CardPart page type.

To create a sales order processor queue page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. In the Table text box, click the AssistButton, select the table 9053 Sales Cue, and then click OK.

  4. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  5. In the Caption field of the first row, which has the type Container and the subtype ContentArea, type SalesOrderContainer.

  6. Select a blank row, and on the View menu, click Properties.

  7. Locate the PageType property, and then set the Value field to the page type CardPart.

  8. Close the Properties window.

  9. Click the Caption column in the second row and type For Release. Set Type to Group and set SubType to CueGroup.

  10. Click the next empty line and then from the View menu, click Field Menu.

    The Field Menu window opens, displaying the list of available fields from the SalesCue table (Table 9053).

  11. Select multiple fields by holding down the CTRL key while you click the following fields:

    • Sales Quotes - Open

    • Sales Orders - Open

  12. Click outside the Field Menu window.

    A message box appears with the following message: "Do you want to add the fields that are selected in the field menu?".

  13. Click Yes.

  14. Close the Field Menu window.

  15. Click the Caption column in the next empty line and type Sales Orders Released Not Shipped. Set Type to Group and set SubType to CueGroup.

  16. Click the Left arrow to negative indent this line one level.

  17. Click the next empty line and then from the View menu, click Field Menu.

  18. Select multiple fields by holding down the CTRL key while you click the following fields:

    • Ready to Ship

    • Delayed

    • Partially Shipped

  19. Click outside the Field Menu window.

    A message box appears with the following message: "Do you want to add the fields that are selected in the field menu?".

  20. Click Yes.

  21. Close the Field Menu window.

  22. Click the Caption column in the next empty line and type Returns. Set Type to Group and set SubType to CueGroup. Click the Left arrow to negative indent this line one level.

  23. Click the next empty line and then from the View menu, click Field Menu.

  24. Select multiple fields by holding down the CTRL key while you click the following fields:

    • Sales Return Orders - All

    • Sales Credit Memos - All

  25. Click outside the Field Menu window.

    A message box appears with the following message: "Do you want to add the fields that are selected in the field menu?".

  26. Click Yes.

  27. Close the Field Menu window.

  28. On the File menu, click Save. Name your new page Sales Order Processor Queue. Set the ID to 50006.

  29. To run the page, in Page Designer, select the page, and then click Run.

    The RoleTailored client opens and displays the new page.

Expand image Adding Actions to the Sales Order Queue Page

Simon now needs to add actions to the sales order queue page. He knows that the card part page type is special in that he can include actions on individual groups within the page. These actions will then be displayed immediately adjacent to the queues on the page. He also adds code to the OnOpenPage() method to ensure that the work queues update to reflect Susan's current work when the Role Center opens.

To add actions to the sales order queue page

  1. In page 50006, click the For Release group line, click View, and then click Actions.

    Action Designer opens.

  2. In Action Designer, click the Caption column in the first row, and enter New Sales Quote. Set the Type column to Action.

  3. With the first row selected, click View, and then click Properties.

    • Set the RunFormMode property to Create.

    • Set the Image property to Quote.

    • Set the RunObject property to Page Sales Quote

  4. In Action Designer, click the Caption column in the second row, and enter New Sales Order. Set the Type column to Action.

  5. With the second row selected, click View, and then click Properties.

    • Set the RunFormMode property to Create.

    • Set the RunObject property to Page Sales Order

  6. In page 50006, click the Sales Orders Released Not Shipped group line, click View, and then click Actions.

    Action Designer opens.

  7. In Action Designer, click the Caption column in the first row, and enter Navigate. Set the Type column to Action.

  8. With the first row selected, click View, and then click Properties.

    • Set the Image property to Navigate.

    • Set the RunObject property to Page Navigate

  9. In page 50006, click the Returns group line, click View, and then click Actions.

    Action Designer opens.

  10. In Action Designer, click the Caption column in the first row, and enter New Sales Return Order. Set the Type column to Action.

  11. With the first row selected, click View, and then click Properties.

    • Set the RunFormMode property to Create.

    • Set the RunObject property to Page Sales Return Order.

  12. In Action Designer, click the Caption column in the second row, and enter New Sales Credit Memo. Set the Type column to Action.

  13. With the second row selected, click View, and then click Properties.

    • Set the RunFormMode property to Create.

    • Set the RunObject property to Page Sales Credit Memo.

  14. In page 50006 in Page Designer, select the first empty line, click View, and then click C/AL code.

  15. Enter the following code in the OnOpenPage() method:

    CopyCode image Copy Code
    RESET;
IF NOT GET THEN BEGIN
  INIT;
  INSERT;
END;

SETRANGE("Date Filter",0D,WORKDATE - 1);
SETFILTER("Date Filter2",'>=%1',WORKDATE);

  16. Save the page.

  17. Run the page.

Expand image Adding Parts to the Role Center Page

Simon now needs to add his new sales order queue page to Susan's new Role Center. Simon knows that he can create multiple groups with multiple parts on the Role Center, but he will have to create one group that contains two parts, the sales order processer queue page and a notifications page.

To add parts to the Role Center page

  1. Open the Sales Order Processor page (50005) in Page Designer.

  2. Click the Name column in the first row and type SalesOrderRoleCenterContainer. Set the SubType to RoleCenterArea.

  3. Click the Name column in the second row and type PartOneGroup. Set Type to Group and set SubType to Group.

  4. Click the Type column in the third row and set Type to Part.

  5. Click View and then click Properties.

  6. Locate the PagePartID property and click the AssistButton in the value field.

    The Page List window opens.

  7. Click page 50006 Sales Order Processor Queue and then click OK.

  8. Click the Type column in the fourth row and set Type to Part.

  9. Press SHIFT+F4 to view the Properties window.

  10. Set the PartType property to System.

  11. Set the SystemPartID property to MyNotes.

  12. Save the page.

  13. Run the page.

Expand image Next Steps

Simon's next steps are to add the My Customers and My Items parts to the page.

Expand image See Also

Tasks

How to: Create a Page
Touring the RoleTailored Client Pages
How to: Run a Page

Concepts

Page Designer Walkthroughs


Walkthrough: Creating a Wizard Page

Walkthrough: Creating a Wizard Page

In Microsoft Dynamics NAV you can use the Navigate page type to create a wizard page. A wizard page consists of a number of user input screens or steps linked together, enabling users to carry out infrequently performed tasks, such as configuration or specific business tasks.

In Microsoft Dynamics NAV, examples of wizard pages include:

  • Create Interaction, page 5077

  • Create To-do, page 5097

  • Create Opportunity, page 5126

In Microsoft Dynamics NAV, Benjamin, the marketing manager, wants to find an easy way to create To-dos for his salespeople. By using the Navigate page type you can make this task easier for him by breaking it down into smaller, more manageable steps.

Note Note

In Microsoft Dynamics NAV, the Navigate page type is also used for page 344, Navigate.

Expand image About This Walkthrough

This walkthrough provides an overview of how to create the basic elements in a To-do wizard page using Page Designer.

This walkthrough illustrates the following tasks:

  • Creating a wizard page

  • Adding steps to a wizard page

  • Adding the attendee subform

  • Adding wizard buttons

  • Running the page

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license

Expand image Story

Simon is a partner working for CRONUS International Ltd.. Benjamin, the marketing manager at CRONUS, wants Simon to create a wizard page that will enable him to create To-dos for his team of salespeople. Simon must create a wizard page that makes it easy to link a To-do with a sales campaign or sales opportunity. Simon knows that he can do this successfully if he uses the Navigate page type to create a To-do wizard.

Expand image Creating a Wizard Page

Simon must first create a new wizard page in Page Designer.

Note Note

In this walkthrough, to learn about the properties and controls of a wizard page, you will create a wizard page from a blank page. If you are running Microsoft Dynamics NAV 2009 SP1, Object Designer also includes a wizard that you can use to create a wizard page that sets up many properties and controls for you. For more information about the wizard, see How to: Create a Page.

To create a wizard page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. In the Table text box, click the AssistButton, select the table 5080 To-do, and then click OK.

  4. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  5. In the Name field of the first row, which has the type Container and the subtype ContentArea, type Ben's To-dos.

  6. Select a blank row, and on the View menu, click Properties.

  7. Locate the PageType property, and then set the Value field to the page type NavigatePage.

  8. Close the Properties window.

  9. Close the Page Designer window. In the Save As dialog box, type Ben's To-dos and enter a page ID, for example, 50015.

You have successfully created and saved a Navigate page, which you will use to create a To-do wizard. Next you must add steps to the wizard.

Expand image Adding Steps to a Wizard Page

In a wizard page, steps are controls that you place on a Navigate page to enable it to work like a wizard. These controls initially appear as tabs in the content area of the page. Simon can create steps in Page Designer by adding a different group element for each step that he wants to create. Each control is displayed as a separate step to the user. The following procedure shows how to create the first step in a To-do wizard that has four steps.

To add steps to a wizard page

  1. Open your new wizard page, 50015 in Page Designer.

  2. In the second row, type Step1 in the Name field. Set Type to Group and SubType to Group.

  3. In the next empty row, leave the Name field blank and set Type to Field.

  4. On the View menu, click Field Menu.

    In the Field Menu window, select fields from the table 5080 To-do.

  5. Make your selection by holding down the CTRL key while you click the following fields:

    • Type

    • Date

    • Description

    • Start time

    • Duration

    • Team To-do

    • All Day Event

    • Ending Date

    • Ending Time

  6. Click OK. A message box displays the following message, "Do you want to add the fields that are selected in the field menu?" Click Yes.

    If the OK and Cancel buttons are unavailable, see Page Designer Troubleshooting for more information.

  7. In the caption field for each of the fields you added, type the following captions:

    • What is the type of the to-do?

    • What is the starting date of the to-do?

    • Describe your to-do

    • What is the start time of the to-do?

    • What is the duration of the to-do?

    • Team to-do

    • All Day Event

    • What is the end date of the to-do?

    • What is the end time of the to-do?

    All the fields that you add must be indented one space below Step 1. Remember to check indentation on all elements that you create, and adjust with the left and right arrows if necessary.

  8. When you have added all the necessary steps, close the Page Designer, and save your page.

    In the RoleTailored client, each step is displayed like a tab control until you add Back, Next, and Finish buttons to the lower part of the page.

Expand image Adding the Attendee Subform

When Ben opens his new wizard page for the first time, he wants to be able to choose a salesperson to create a To-do for. Simon must add a control to Step 1 of the wizard, which allows him to select attendees from table 5080, Attendees.

To add the attendee subform

  1. Open your new wizard page, 50015 in Page Designer.

  2. Select the next available row below Step1. Right click, and click New to insert a new row.

  3. Type AttendeeSubForm in the Name field, this row should be indented to match the other field elements in the Step 1 group. Set Type to Part.

  4. Click View, and then click Properties to open the Properties window. Set the PagePartID property to Attendee Wizard SubForm. This will ensure that Ben can select attendees for his To-dos in the first step of the wizard.

  5. Close and save your page. Preview your changes in the RoleTailored client.

    The following illustration shows the indentation of elements on the wizard page after adding steps and the attendee subform.

Note Note

There a number of other variables, constants, and functions that you must define in C/AL Globals before this control can be fully functional. Instructions on how to add these is beyond the scope of this walkthrough.

Expand image Adding Wizard Buttons

Simon has now successfully created a basic wizard page. To make his page appear more like a wizard he must add Next, Back, and Finish buttons. To do this, Simon must add a new set of actions to his wizard page using the Action Designer.

To add wizard buttons

  1. Open your new wizard page 50015, in Page Designer.

  2. Select the first empty row below the steps that you have already created. Click View, and then click Actions to open Action Designer.

  3. On the first empty row in Action Designer, set Type to ActionContainer and SubType to ActionItems.

  4. In the next available row, type Back in the Name field, and set Type to Action. Do the same in the next two available rows except enter Next and Finish in the Name fields. When you have added all the buttons you need, select the row with the Back button control, and open the Properties window.

  5. In the Properties window, set the following properties on the Back button.

    Property Value

    Enabled

    BackEnable

    Visible

    True

    RunFormMode

    Edit

    InFooterBar

    Yes

  6. Save and compile your page.

Expand image Running the Page

Test your new wizard page in the RoleTailored client.

To run the page

  • In Page Designer, select page Ben's To-dos, and then click Run.

    The RoleTailored client opens and displays the new wizard page.

Expand image Next Steps

Simon has now created a basic wizard page. He must remember to add the variables, constants, and functions necessary to make the wizard page function correctly. He would also like to add a promoted action called 'Find' to Step 1 of the wizard, to help Ben to search for attendees.

For more information about adding variables, constants, and functions, see Developing Codeunits.

Expand image See Also

Tasks

How to: Add Actions to a Page
How to: Add Actions to the Action Pane on Pages
How to: Create a Page
Touring the RoleTailored Client Pages
How to: Run a Page


Walkthrough: Creating a Document Page

Walkthrough: Creating a Document Page

In Microsoft Dynamics NAV, a document page consists of two separate pages, with one page nested inside the other page. The Header and Line form in the Classic client provides similar functionality by combining a main form with a subform.

You can create a document page if you have two tables that are linked. For example, page 42, Sales Order, has two source tables: Sales Header and Sales Lines. These two tables are linked in a one-to-many relationship and are ideal source tables for the Sales Order page.

The Sales Order document page consists of a series of FastTabs that display customer, invoicing, shipping, and other relevant information. The source table for this information is table 36, Sales Header. The lines that show items associated with each customer are based on table 37, Sales Lines.

In this walkthrough, you will create a sales order document page for Susan, the order processor. This page is essential to Susan’s daily work, because she uses sales orders to create and track all her customer orders from the creation of the first quote to when the order is shipped. This page also contains useful secondary information, such as customer statistics, in FactBoxes to the right of the main content area. For example, a Factbox can be added that is updated every time you select a line.

Expand image About This Walkthrough

This walkthrough provides an overview of how to create a sales order document page with Page Designer.

The walkthrough illustrates the following tasks:

  • Creating a document page

  • Adding controls to display fields from the Sales Header table

  • Adding a Part Control to display sales lines

  • Adding a FactBox that is linked to sales lines

  • Running the page

Expand image Story

Simon is a partner working for CRONUS International Ltd. Susan asks Simon to create a sales order page for her that can display each of her customers and any associated orders. Simon knows that this page must be based on two related source tables and that he must create a page using the document page type.

Prerequisites

The following prerequisites are required for this walkthrough:

  • Microsoft Dynamics NAV 2009 installed with a developer license.

Expand image Creating a Document Page

First, Simon creates a new document page that is based on table 36, Sales Header.

Note Note

In this walkthrough, to learn about the properties and controls of a document page, you will create document page from a blank page. If you are running Microsoft Dynamics NAV 2009 SP1, Object Designer also includes a wizard that you can use to create a document page that will set up many properties and controls for you. For more information about the wizard, see How to: Create a Page.

To create a document page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. In the Table text box, click the AssistButton, select the table 36, Sales Header, and then click OK.

  4. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  5. In the Name field of the first row, which has the type Container and the subtype ContentArea, type Susan's Sales Order Page.

  6. Select a blank row, and on the View menu, click Properties.

  7. Locate the PageType property, and then set the Value field to the page type Document.

  8. Close the Properties window.

  9. In the next row in Page Designer, in the Name field, type General.

  10. Set the Type property to Group and the SubType property to Group.

  11. On the File menu, click Save. Name your new page Susan's Sales Order Page. Set the ID field to 50006.

Expand image Adding a Control to Display Fields from the Sales Header Table

Simon now wants to add fields to his document page. He creates a group called General and adds fields from the Sales Header table. He knows that the main content area on a document page displays fields as FastTabs in the RoleTailored client.

To add a control to display fields from the Sales Header table

  1. In Page Designer, select the next empty row below the General group and set the Type property to Field.

  2. Select the row, and on the View menu, click Field Menu. The Field Menu displays all fields that are available in the Sales Header table.

  3. Press the CTRL key and select the following rows:

    • Sell-to Customer No.

    • No.

    • Sell-to Customer Name

    • Sell-to Address

    • Sell-to Address 2

    • Sell-to City

    • Sell-to Contact

  4. Click OK, and then click Yes to add the fields to your page.

    Note Note

    If the OK and Cancel buttons are unavailable, see Page Designer Troubleshooting for more information.

  5. On the File menu, click Save.

  6. In the Save dialog box, make sure Compiled is selected, and then click OK.

Expand image Adding a Part Control to Display Sales Lines

Simon's next task is to add a nested control to display lines from the Sales Lines table and the Sales Order Subform page. To do this, he must add a Part control to his page and link both objects using the Properties window.

To add a part control to display sales lines

  1. In Page Designer, select the next empty row below the General group and set the Type property to Part.

  2. In the Name field, type Sales Lines. Click anywhere outside this field, and Caption is filled in automatically.

  3. Select the Sales Lines row, and on the View menu, click Properties.

  4. In the Properties window, you can view the properties of the Sales Lines control. Set two properties here to configure your link to the Sales Lines table and page 46, Sales Order Subform:

    • PagePartID

    • SubFormLink

  5. To set the PagePartID property, in the Properties window, click the AssistButton next to this property.

  6. In the Page List window, select page 46, Sales Order Subform, and then click OK.

  7. To set the SubFormLink property, click the drill-down control to open the Table Filter window.

  8. In the first row, click Field to open the Sales Line - Field List window. This window enables you to set a table filter on the Sales Lines table.

  9. Select Document No., and then click OK.

  10. In the Type drop-down, click FIELD.

  11. In the Value field, click the AssistButton, select No., and then click OK.

  12. In the Table Filter window, click OK to add this filter value to the SubFormLink property.

  13. Use the left and right arrows to indent Sales Lines so that it matches the General group element.

Expand image Adding a FactBox That Is Linked to Lines

Simon has already created two FactBoxes for his Sales Order page. He now wants to link the Sales Line FactBox to the Sales Lines table on his document page. To do this, he must change the ProviderID property on his FactBox part after he has added it to the page.

To add a FactBox that is linked to lines

  1. In Page Designer, select the next empty row.

  2. Set the Type field to Container, and then set the SubType field to FactBoxArea. Accept the default values for the Name and Caption fields.

  3. In the next row, type SalesLineFactBox in the Name field, and then set the Type field to Part.

    Note Note

    When you select the Part field as Type, you cannot select a SubType.

  4. On the View menu, click Properties.

  5. In the Properties window, select the PagePartID property, and then click the AssistButton. Select page 9087, Sales Lines FactBox, from the Page List window, and then click OK.

  6. To create a link between the FactBox and Sales Lines, you must first find the ID property of the Sales Lines row. To do this, select the Sales Lines row, and view the Properties window. In this example, the ID property of the Sales Lines row is 12. Select the SalesLineFactBox and set the ProviderID property to 12.

    Note Note

    The ID property of the Sales Lines row can vary, so check this carefully. Do not use the value mentioned in this example.

  7. In the SubFormLink property, enter the following table filter.

    Document Type=FIELD(Document Type),Document No.=FIELD(Document No.),Line No.=FIELD(Line No.)

  8. Close the Properties window.

  9. Check the indentation on your FactBox. Indentation of your FactBox container should match the first element in the page so that there is no indentation. Your SalesLineFactBox part should be indented by one space below the FactBox container.

    In Page Designer, your Document page should look like the following illustration.

  10. Close Page Designer, and then click Yes to save your page.

Expand image Running the Page

Test your new document page in the RoleTailored client.

To run the page

  1. On the taskbar, click Start, and then click Run.

  2. Enter the following command to display your page:

    DynamicsNav:////runpage?page=<pageid>

    The RoleTailored client opens and displays the new document page.

Expand image Next Steps

Simon now wants to add actions to Susan's document page and promote some of these actions to the Action Pane.

Expand image See Also

Tasks

How to: Add Actions to a Page
How to: Add Actions to the Action Pane on Pages
How to: Create a Page
Touring the RoleTailored Client Pages
How to: Run a Page

Concepts

Pages Overview


Walkthrough: Creating a Worksheet Page

Walkthrough: Creating a Worksheet Page

In Microsoft Dynamics NAV you can use a worksheet page type to create two types of pages:

  • Worksheet pages - To present data in a list and offer a choice of actions to the user. For example, page 5841, Standard Cost worksheet.

  • Journal pages - To perform tasks, such as posting transactions. For example, page 40, the Item Journal.

Worksheet pages always open in edit mode and can display lists of data in a grid control and in lines. Lines can be filled in by a user or by running a batch job. You can add other controls to a worksheet page, such as a filter or FactBox, but you cannot add a chart pane. These controls can also be added or removed by the user as part of their user personalization options. Actions can be added to the navigation of a worksheet page, some of which may be promoted by the user to the Action Pane.

In this walkthrough, you learn how to create a new item journal worksheet that displays item journal lines for Susan, the order processor. Susan often uses the posting action on the Item Journal page to adjust her inventory in relation to purchases and sales.

Expand image About This Walkthrough

This walkthrough provides on overview of how to create a journal worksheet page and how to add controls to display items from table 83 Item Journal Line.

This walkthrough illustrates the following tasks:

  • Creating a worksheet page

  • Adding a batch name control

  • Adding a field repeater control

  • Adding a fixed layout control

  • Adding FactBoxes

  • Running the page

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license

Expand image Story

Simon is a partner working for CRONUS International Ltd.. Susan, the order processor asks Simon to create an Item Journal worksheet page for her, which she can use to keep her item inventory up to date.

Expand image Creating a Worksheet Page

Note Note

In this walkthrough, to learn about the properties and controls of a worksheet page, you will create worksheet page from a blank page. If you are running Microsoft Dynamics NAV 2009 SP1, Object Designer also includes a wizard that you can use to create a worksheet page that sets up many properties and controls for you. For more information about the wizard, see How to: Create a Page.

To create a worksheet page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box appears.

  3. In the Table text box, click the AssistButton, select the table 83, Item Journal Line, and then click OK.

  4. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  5. In the Name field of the first row, which has the type Container and the subtype ContentArea, type Susan's Item Journal.

  6. Select a blank row, and on the View menu, click Properties.

  7. Locate the PageType property, and then set the Value field to the page type Worksheet.

  8. Close the Properties window.

Expand image Adding a Batch Name Control

First, Simon needs to add a batch name control to the top of his worksheet page, so Susan can select which batch item she wants to run from the Item Journal Batch table.

To add a batch name control

  1. In Page Designer, select the second row, type CurrentJnlBatchName in the Name field, and set Type to Field. This element is automatically indented one space below your Container element.

  2. With the second row still selected, open the Properties window, and set the SourceExpr property to CurrentJnlBatchName.

    Note Note

    Your page will not compile until you have added the CurrentJnlBatchName variable to C/AL Globals.

  3. Set the LookUp property to Yes.

  4. Save your new page and name it Susan's Item Journal. Set the page ID to 50007 or another value in the 50000 range.

Note Note

There a number of other variables, constants, and functions that you must define in C/AL Globals before this control can be fully functional. Instructions on how to add these is beyond the scope of this walkthrough.

Expand image Adding Field a Repeater Control

Next, Simon must use the Field Menu to add fields to Susan's Item Journal page. In a worksheet page these fields are displayed horizontally, like lines.

To add field repeater controls

  1. Open page 50007, Susan's Item Journal in Page Designer.

  2. In the third row, type a Name for your control or leave it blank. Set Type to Group and SubType to Repeater. If you have left the Name field blank, when you click outside this row, a default name for this control is added automatically.

  3. In the next blank row, set Type to Field. You cannot set a SubType when you select Field.

  4. With the new Field row selected, click View, and then click Field Menu. The Field Menu window displays fields available from table 83, Item Journal Line. Select multiple fields from this table by holding down the CTRL key while you make your selection. For this walkthrough select the following fields:

    • Posting Date

    • Document Date

    • Entry Type

    • Document No.

    • External Document No.

    • Item No.

    • Variant Code

    • Description

    If the OK and Cancel buttons are unavailable, see Page Designer Troubleshooting for more information.

    You have now successfully added a Repeater control to your worksheet page.

  5. Close the Page Designer window and save your changes.

Expand image Adding Fixed Layout Controls

Next, Simon needs to create a Fixed Layout control. On an Item Journal page, this type of control can be used to show a description at the bottom of the page for the item displayed in the batch line.

To add a fixed layout control

  1. Open page 50007, Susan's Item Journal in Page Designer.

  2. In the next available row below the repeater controls, set Type to Group and SubType to Group. Negative indent this row one space, using the arrows provided in Page Designer. Your fixed layout control should be indented at the same level as your repeater control.

  3. On the next row, set Type to Group and SubType to FixedLayout.

  4. In the next available row, set Type to Group and SubType to Group.

  5. Finally, in the next available row, set Type to Field. Type Item Description in the Name field and accept the default indentation as you add these elements to the page.

  6. Save and preview your page. You can now see that Item Description is displayed at the bottom of your worksheet page.

    Note Note

    To link Item Description to Batch Lines you must add the variable Item Description to C/AL Globals in Object Designer.

Expand image Adding FactBoxes

Simon has decided to add three FactBoxes to Susan's worksheet page:

  • Item Replenishment

  • RecordLinks

  • Notes

Item Replenishment is a FactBox based on an existing page, while RecordLinks and Notes are both system FactBoxes. Simon wants all these FactBoxes to be hidden unless Susan decides to show them as part of her personalization options.

To add FactBoxes to a worksheet page

  1. Open page 50007, Susan's Item Journal in Page Designer.

  2. In the first available empty row, set Type to Container and SubType to FactBoxArea. Click anywhere outside this row to accept the default value in the Name field.

  3. Use the left indentation arrow to negative indent your FactBox until it has zero indention and matches the top level ContentArea container element.

  4. In the next row, set Type to Part, and accept all other default values in this row.

  5. With the same row selected, click View, and then click Properties to open the Properties window. Set the PagePartID property to Item Replenishment FactBox.

  6. Set the Visible property to FALSE. This FactBox remains hidden until the user decides to add it to the page.

  7. Close the Properties window.

  8. In the next available empty row, add another Part for the RecordLinks FactBox.

  9. Open the Properties window.

  10. In the Properties window, set the following properties.

    Property Value

    SystemPartID

    RecordLinks

    PartType

    System

    Visible

    FALSE

  11. In the next available empty row in Page Designer, add another Part for the Notes FactBox.

  12. Open the Properties window.

  13. In the Properties window, set the following properties.

    Property Value

    SystemPartID

    Notes

    PartType

    System

    Visible

    FALSE

  14. Close the Properties window.

  15. Check the indentation of your page elements and adjust if necessary.

  16. Close and save your page.

    The following illustration shows the indentation of elements on the worksheet page after adding FactBoxes.

Expand image Running the Page

Test your new worksheet page in the RoleTailored client.

To run the page

  • In Page Designer, select the page, and then click Run.

    The RoleTailored client opens and displays the new worksheet page.

Expand image Next Steps

Simon has now created a basic worksheet page. He must remember to add the variables, constants, and functions necessary to make the worksheet page function correctly. He would also like to add some posting actions, some of which he will promote to the Action Pane.

For more information about adding variables, constants, and functions, see Developing Codeunits.

Expand image See Also

Tasks

How to: Add Actions to a Page
How to: Add Actions to the Action Pane on Pages
Page Designer Troubleshooting
How to: Create a Page
Touring the RoleTailored Client Pages
How to: Run a Page


Walkthrough: Creating a Cue on a Role Center

Walkthrough: Creating a Cue on a Role Center

The following walkthrough demonstrates how to add a Cue on the RoleTailored client. A Cue provides a way to graphically show the number of entities in a table and view the entities in a filtered list. For example, the Cue can show total number of open invoices, sales orders, or credit memos. As shown in the following figure, a Cue is an icon that depicts a stack of papers on the page, where the height of the stack roughly indicates the number of entities in an underlying table. A number value on each Cue gives the precise count. The Cue provides a shortcut link to a filtered list page for displaying the entities. You can also add actions to a Cue that open related tasks that a user of the Role Center will typically perform.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating the Table Field for Cue Data

  • Creating a Cue on a Card Page for the Role Center

  • Adding an Action to the Cue

  • Adding the Cue Card Part Page on the Role Center Page

Roles

This walkthrough demonstrates tasks performed by the following user roles:

  • Microsoft .NET developer.

  • Microsoft Dynamics NAV developer and IT pro.

Prerequisites

To complete this walkthrough, you need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements met. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

  • Microsoft Dynamics NAV 2009 demo database. The walkthrough uses the following objects:

    • Table 36, Sales Header

    • Page 9006, SO Processer Role Center

    • Page 9301, Sales Invoice List

    • Page 43, Sales Invoice

Expand image Story

Simon is a software developer who is working for CRONUS International Ltd. He has been asked to add a Cue to the Role Centers of sales order processors. The Cue will show how many open sales invoices that they have. To accomplish this, Simon will create a Cue that extracts the number of open sales invoices from the Sales Header table. He will place the Cue in a part on the Order Processor Role Center page. He will also add an action that allows users to create a new sales invoice from a link on the Cue. The Cue will look similar to the previous figure.

Expand image Creating the Table Field for Cue Data

To calculate the number of open sales invoices, Simon creates a table that includes a FlowField that extracts data from the Sales Header table and calculates how many opens sales invoices exist. Because a table must have at least one data field and a FlowField is based on a calculation and not considered an actual data field, Simon adds a dummy primary key field that does not yield any data. For more information about FlowFields, see FlowFields Overview.

To create a table that includes fields for the Cue data

  1. In the Classic Client, on the Tools menu, click Object Designer.

  2. Click Table, and then click New.

  3. In the first empty row, in the Field Name, type Primary Key and set the Data type to Code.

  4. In the next empty row, in the Field Name, type Sales Invoices - Open and set the Data type to Integer.

    This defines the Cue data field.

To define a filter on the cue data field

  1. Click the Sales Invoices - Open field row, and then on the View menu, click Properties.

  2. In the Properties window, set the FieldClass property to FlowField.

  3. In the CalcFormula property, click the AssistEdit button to open the Calculation Formula window.

  4. In the Calculation Formula window, set the Method field to Count and the Table field to Sales Header.

  5. In the Table Filter field, click the AssistEdit button to open the Table Filter window.

  6. In the first line of the Table Filter window, click the AssistEdit button.

  7. In the Sales Header - Field List window, select Document Type, and then click OK to return to the Table Filter window.

  8. In the Document Type row, set the Type column to FILTER and type Invoice in the Value column. This filters the Sales Header table on sales invoices.

  9. On the next empty row, click the AssistEdit button.

  10. In the Sales Header - Field List window, select Status, and then click OK to return to the Table Filter window

  11. In the Status row, set the Type column to FILTER and type Open in the Value column. This filters the Sales Header table on open sales invoices.

    The Table Filters window will look similar to the following figure:

  12. Click OK until you return to the Properties window, and then close the Properties window to return to Table Designer.

To save the table

  1. On the File menu, click Save.

  2. In the ID field, type a number that will serve as a unique table identifier.

    Note Note

    There are restrictions about which numbers you can use. Contact your Microsoft Certified Partner for information.

  3. In the Name field, type Sales Invoice Cue.

  4. Select the Compiled check box.

  5. Click OK.

To set the table primary key and save the table

  1. In Table Designer, select an empty row, and then on the View menu, click Keys.

  2. In the Keys window, select the first line, and then in the Key column, select the AssistEdit button.

  3. In the Field List window, select the first row, and then click the AssistEdit button.

  4. Select Primary Key field, and then click OK until you return to the Keys window.

  5. Close the Keys window to return to Table Designer.

Expand image Creating a Cue on a Card Page for the Role Center

To display the Sales Invoice Cue on the Role Center, Simon creates a card part page type that has a CueGroup control that includes the Sales Invoices - Open field of the Sales Invoice Cue table. Simon also needs to initialize the data field on the Cue with a record, so he adds code to the OnOpenPage trigger of the card part page type.

To create the card part page for the Sales Invoice Cue

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page, and then click New. The New Page dialog box opens.

  3. In the Table text box, click the AssistButton to open the Table List window.

  4. Select the Sales Invoice Cue table that you created in the previous procedure, and then click OK to return to the page wizard,

  5. Click Create blank page, and then click OK.

    The new page appears in Page Designer.

  6. In the Caption field of the first row, which has the type Container and the subtype ContentArea, type SalesInvoiceContainer.

  7. Select a blank row, and then on the View menu, click Properties.

  8. Locate the PageType property, and then set the Value field to CardPart.

  9. Close the Properties window to return to Page Designer.

To add the Sales Invoice Cue on the card part page

  1. In the row after the ContentArea row, set Type to Group and set SubType to CueGroup. In the Caption column, type Sales Invoices.

    The Caption value defines the heading for the Cue that appears on the Role Center.

  2. On the next row, set the Type column to Field. In the Caption column, type Open. The Caption value defines the text that appears below the Cue.

  3. With the row selected, on the View menu, click Field Menu.

    The Field Menu window opens and displays the list of available fields from the Sales Invoice Cue table.

  4. Select Sales Invoices - Open field, and then click OK.

    Page Designer should look similar to the following figure:

  5. To create a link from the Cue to the Sales Invoice List page for displaying the open invoices, select the Sales Invoices - Open field row, and then on the View menu, click Properties.

  6. In the Properties window, set the DrillDownFormID property to Sales Invoice List.

  7. To initialize the cue with a record when the page opens, you must add code to the page's OnOpenPage trigger. In Page Designer, select an empty row, and then on the View menu, click C/AL code.

  8. In the C/AL Editor, type the following code in the OnOpenPage trigger:

    CopyCode image Copy Code
    RESET;
IF NOT GET THEN BEGIN
  INIT;
  INSERT;
END;

  9. Close the C/AL Editor.

To save the sales invoice Cue card part

  1. On the File menu, click Save.

  2. In the ID field, type a number that will serve as a unique page identifier.

    Note Note

    There are restrictions about which numbers you can use. Contact your Microsoft Certified Partner for information.

  3. In the Name field, type Sales Invoice Cue.

  4. Select the Compiled check box.

  5. Click OK.

  6. To run the page, in Page Designer, select the page, and then click Run.

  7. The RoleTailored client opens and displays the new page.

Expand image Adding an Action to the Cue

Simon wants to add a link on the Cue that allows the user to create a new sales invoice. To accomplish this, he creates an action on the CueGroup control that targets the Sales Invoice page.

To add actions to the sales order queue page

  1. In Page Designer for Sales Invoice Cue page, select the Sales Invoices CueGroup row.

  2. On the View menu, click Actions.

  3. In the first row of Action Designer, in the Caption column, type New Sales Invoice and set the Type column to Action.

  4. With the first row selected, on the View menu, click Properties.

  5. In the Properties window, do the following:

    • Set the RunFormMode property to Create.

    • Set the RunObject property to Page Sales Invoice

  6. Run the page.

Expand image Adding the Cue Card Part Page on the Role Center Page

To display the Sales Invoice Cue on the Role Center, Simon must add the Sales Invoice Cue card part page to the Role Center page for sales order processors. To do this, he adds a part to the SO Order Processor page that targets the new Cue page.

To add the Sales Invoice Cue to the Role Center page

  1. In Object Designer, click Page to display the list of pages.

  2. Locate page 9060, SO Order Processor, and then click Design.

  3. In Page Designer, locate the Group control in which you want to include the Sales Invoice Cue page.

  4. To insert a new row, right-click a row below the Group control, and then click New.

  5. In the new row, set the Type column to Part.

  6. On the View menu, click Properties.

  7. Set the PartType property to Page.

  8. In the PagePartID property, click the AssistButton button in the value field.

    The Page List window opens.

  9. Click the page Sales Invoices and then click OK.

  10. Save the page.

  11. Run the page.

Expand image See Also

Tasks

Touring the RoleTailored Client Pages
Walkthrough: Creating a Role Center

Concepts

Pages Overview
Designing Tables


Creating and Maintaining Forms

Creating and Maintaining Forms

In previous versions of Microsoft Dynamics NAV, and in the Classic client in Microsoft Dynamics NAV 2009 forms have been the basis for the user interface. Customers use forms for tasks like creating sales invoices and purchase orders, tracking the general ledger balance, and working with warehouse items. XML-based pages have replaced forms in the RoleTailored client.

Deciding Between Forms and Pages

There are two reasons to use Form Designer to create forms in Microsoft Dynamics NAV 2009:

  • To support businesses that use the Classic client, which works with forms instead of pages.

  • To prepare custom forms to be transformed into pages, which are then deployed in the RoleTailored client.

You can use the form transformation tool to transform existing forms to pages. If you have some forms that cannot be successfully transformed, you may need to manually revise them to meet new criteria for pages and then transform them.

The following tables link to topics that help you create and modify pages, create and modify forms, and revise and transform forms.

Creating and Modifying Pages for the RoleTailored Client

I used to | Now I will | More information
Create a new form by clicking New in the Form Designer. | Create a new page by using the Page Designer. | How to: Create a Page
Create a list form by selecting List in the Form Wizard. | Create a list page by selecting List in the Page Designer. | How to: Create a Page and Touring the RoleTailored Client Pages
Modify a form by using the Form Designer. | Modify a page by using the Page Designer. | Adding Actions to Pages

Form Fundamentals

To | See
Learn the purpose and function of forms in Microsoft Dynamics NAV applications. | Forms Overview
Learn the types of controls and how they are used on forms. | Controls Overview
Learn the definition of bound and unbound, and how these terms apply to forms and controls. | Bound and Unbound Forms and Controls
Learn about controlling the behavior of forms and controls. | Form and Control Properties
Learn about activating a function when designated events occur. | Triggers Overview

Creating Forms

To | See
Create a new form by clicking New in Form Designer. | How to: Create a Form with a Form Wizard
Create a card form by selecting Card in Form Designer. | How to: Create a Card Form
Create a tabular form by selecting Tabular-type Form in Form Designer. | How to: Create a Tabular Form
Create a form without using the Form Designer wizard. | How to: Create a Form Without a Wizard
Save a form, compile it, and run it. | Saving, Compiling, and Running Forms

Designing Forms

To | See
Learn about using controls to design forms, including types of controls, how to create controls, and how to customize controls. | Working with Controls
Learn about form properties, including how to change properties, properties that influence the look and feel of the form, and properties that control input. | Working with Properties
Learn about using controls in applications, including managing text and value display, adding shapes and pictures, and creating controls like buttons, check boxes, and options. | Using Controls in Applications

Extending Forms

To | See
Learn about designing main forms and the subforms within those forms. | Main Forms and Subforms
Read about adding look-up functionality to a form. | Looking Up Values and Validating Entries
Learn about viewing underlying transactions from FlowFields. | Drilling Down to Underlying Transactions
Learn about launching one form from another form. | Opening Another Form

Transforming Forms

To | See
Learn about transforming forms to pages, including when forms have to be transformed, and the transformation process. | Transforming Forms to Pages
Prepare forms for transformation and prepare the transformation tool input. | Preparing to Transform Forms to Pages
Run the transformation tool. | Transforming Forms
Follow step-by-step procedures that show how to perform a transformation of a standard application form. | Walkthrough: Transforming a Standard Application Form
Learn about form transformation mapping rules, code rules, redesigned forms in the standard application, and other references. | Form Transformation Reference

See Also

Concepts

Creating and Maintaining Pages
Designing and Maintaining Reports


Form Fundamentals

Form Fundamentals

Forms are used to enter and display data. For example, you can use a form to enter information about new customers or to update and review information about existing customers. This section introduces the fundamental concepts and basic tasks involved in designing and using forms.

In This Section

Documentation | Description
Forms Overview | This topic introduces the concept of forms.
Controls Overview | This topic describes what controls on forms are.
Bound and Unbound Forms and Controls | This topic introduces the concepts of bound and unbound.
Form and Control Properties | This topic provides an overview of properties for both forms and controls.
Triggers Overview | This topic provides an overview of triggers on forms.

See Also

Concepts

Creating Forms
Extending Forms

Other Resources

Designing Forms


Forms Overview

Forms Overview

After creating tables, the next step in developing a C/SIDE application is to design forms. In contrast to programs written in traditional programming languages, C/SIDE applications do not execute sequentially, they are event-driven.

Forms

You use forms to enter information into database tables and to retrieve and display information from them. It is through forms that you generate the events that determine the flow of the application.

Forms can be used to access one table at a time, or they can combine information from different tables. A form can display information that is calculated on the fly as the form is displayed, and it can contain information (such as a label) that is not related to any table, or purely decorative elements (such as bitmap pictures).

See Also

Concepts

Form Fundamentals


Controls Overview

Controls Overview

All the information displayed in a form is presented in controls. Controls are objects that can display data from a database table field, the value of a C/AL expression, bitmap pictures, or static information such as descriptive text.

Controls

Some controls are called container controls. A frame is a container control and does not display data or information but acts as a container for other controls. The tab control is another container control. Tabs are made up of frames or pages stacked on top of each other. You click tabs to switch between pages. Tab controls are another way to group information on a form. Tabs are useful controls because they help avoid clutter and make it easy to move from one page to another. Control branches consist of a parent control, and subordinate or child controls. An example is a text box and a label. The child control inherits some properties from the parent, and the entire branch can be moved together.


Bound and Unbound Forms and Controls

Bound and Unbound Forms and Controls

Forms and controls on forms can either be bound or unbound. This topic explains some of the differences.

Bound and Unbound

Typically, a form is bound to a database table. The form is used to enter information into the table and to display information from that table. An unbound form is not related to a table. An example of an unbound form is a menu from which you can choose to run other forms or reports.

Controls on a form that is bound to a table are usually bound to fields in the same table. There does not have to be a control for every field, nor do all controls need to be bound to fields. Controls that are not bound to fields are unbound controls. For example, a command button that prints the information on the form and a control that contains a descriptive text are unbound controls. Unbound controls include controls that display information that is calculated as the form is displayed. This information is based on the underlying table, or on values that are entered by the user. A blank form is unbound when it is created.


Form and Control Properties

Form and Control Properties

Properties are used to define the behavior of forms and controls. This topic introduces form and control properties.

Properties

Properties are used to define how a control is placed on a form, what field it is related to in the underlying table, and what happens when information is entered into the field. Different types of controls have different sets of properties. For example, a text box usually displays the contents of a database field and has more properties than a picture box.

The form itself also has properties. For example, you can specify whether the form should only be used for displaying information, for inserting new records, or for updating existing records. Properties are defined on the Properties window, which can be edited when the form is opened in Form Designer.


Triggers Overview

Triggers Overview

Triggers activate a function when a certain event occurs. This topic introduces the concept of triggers. For more information, see Defining Form and Control Triggers.

Triggers

When C/AL functions are executed as a result of a predefined event on either a form or a control, the event triggers the function. Together the event and function make a trigger.

Form triggers include OnOpenForm and OnModifyRecord. OnOpenForm is a statement that is executed when the form opens. OnModifyRecord is a statement that is executed before accepting changes that the user has made to a record. Triggers are edited in the C/AL editor that can be opened from Form Designer.

See Also

Concepts

Forms Overview
Controls Overview
Bound and Unbound Forms and Controls
Form and Control Properties


Creating Forms

Creating Forms

Forms can be created manually or by using a form wizard. This topic introduces forms. For more information, see Forms Overview.

Forms

Forms can be created and designed manually. Although this method gives you the most control, it may take some time to learn this technique. Alternatively you can use a form wizard, which is fast and easy and the preferred method to use when you are just beginning to create forms. A form wizard prompts you for the minimum amount of information needed to create a form and then does the rest of the work. After the form has been created by the wizard, you can use Form Designer to alter it to meet your requirements.

You can create two kinds of forms in Microsoft Dynamics NAV.

  • Card forms that display one record at a time.

  • Tabular forms that display several records at a time.

You can use the form wizard to create both kinds of forms.

See Also

Concepts

Form Fundamentals
Forms Overview


How to: Create a Form with a Form Wizard

How to: Create a Form with a Form Wizard

You can use the form wizard to create forms. The following procedure describes the process.

To create a form with the form wizard

  1. Click Tools, and then click Object Designer to open the Object Designer window.

  2. In Object Designer, click Form to open Form Designer.

  3. Click the New button to open the New Form window.

  4. If you create a form that is related to a table, type the name of the table in the Table field. Alternatively, click the lookup button and select the table from a list.

  5. Select the Create a form using a wizard option.

  6. Select the type of form that you want the wizard to create: a card form or a tabular form. Click OK.

See Also

Concepts

Creating Forms


How to: Create a Card Form

How to: Create a Card Form

Using the form wizard you can create a card form or a tabular form. This topic describes how to use the form wizard to create a card form. For more information about how to use the form wizard, see How to: Create a Form with a Form Wizard.

To create a card form

  1. In the form wizard, select Card-Type Form, and then click OK. The Card Form Wizard opens.

  2. Choose between a plain form and a form with tab pages. Enter a caption or name for each tab that you want and click Next.

  3. From Available Fields, select the fields that you want to include on your form by using the arrows.When creating a form with tab controls, choose the tab on which you want the fields to appear. Switch between the tabs by clicking them.

  4. Use the Separator button to insert vertical space between the controls. Insert column breaks by clicking the Column Break button.If you need more than three columns, consider creating tab pages instead.

  5. Click Preview to see what your form looks like.

  6. Close the form, and click Yes to save it. The Save As window appears. Enter an ID number, enter a name for the new form, and choose whether to compile the form now. To compile the form later, select the form in Object Designer, and click Tools, and then click Compile.

See Also

Tasks

How to: Create a Form with a Form Wizard


How to: Create a Tabular Form

How to: Create a Tabular Form

Using the form wizard you can create a tabular form or a card form. This topic describes how to use the form wizard to create a tabular form. For more information about how to use the form wizard, see How to: Create a Form with a Form Wizard.

To create a tabular form

  1. In the form wizard, select Tabular-Type Form, and then click OK. The Tabular Form Wizard opens.

  2. From Available Fields, select the fields you that want to include on your form by using the arrows.

  3. Click Preview to see what your form looks like.

  4. When you are done designing the form, click Finish and the form is opened in Form Designer.

  5. In Form Designer, you can manually adjust the form.

  6. Close the form, and click Yes to save it. The Save As window appears. Enter an ID number, enter a name for the new form, and choose whether to compile the form now. To compile the form later, select the form in the Object Designer, click Tools, and then click Compile.

See Also

Tasks

How to: Create a Form with a Form Wizard


How to: Create a Form Without a Wizard

How to: Create a Form Without a Wizard

You can create new forms by using a wizard or by designing them yourself. This topic describes how to create a form without using a wizard.

To create a form without a wizard

  1. Click Tools, and then click Object Designer.

  2. In the Object Designer, click Form, and then click New. The New Form window opens.If you are creating a form that is related to a table, type the name of the table in the Table field. Alternatively, click the AssistButton and select the table from a list.

  3. Select Create a blank form, and then click OK. Form Designer opens an empty form. Add controls, labels, and set properties for this form. For more information, see Designing Forms.

  4. Close Form Designer, and click Yes to save the form. Enter an ID number, enter a name for the new form, and choose whether to compile the form now. To compile it later, select the form in the Object Designer, click Tools, and then click Compile.

See Also

Other Resources

Designing Forms


Saving, Compiling, and Running Forms

Saving, Compiling, and Running Forms

After you have designed a form, you must save and compile it before it can be run. Usually, you do this when you have finished designing the form. However, you may want to save a form that is not yet finished and before it can be compiled, particularly if the form contains C/AL code. You can also test compile and test run a form without closing or saving it.

Saving and Closing a Form

A designed form is closed when Form Designer is closed. When you close a form, you need to decide whether you want to save the form. If the form has not yet been saved, you must assign it an ID and a name. The ID must be unique and follow the rules for numbering objects. Your local Microsoft Certified Partner will provide you with this information.

The Compiled option field is selected by default. If your form is not ready to be compiled, remove the check mark. Click OK to save the form. To save a form without closing it, click File, and click then Save or Save As. You can also use Save As to give a form a new name.

Compiling a Form

Forms, like the other objects in C/SIDE, must be compiled before they can be run. As described earlier, you can compile a form when you save it. While you are designing a form, you may want to test compile it to find possible errors. This is useful when the form contains C/AL code in triggers. To test compile a form when you are designing, click Tools, and then click Compile.

Running a Form

In a finished application, your forms are incorporated into menus or they are called from other forms. However, when you are designing forms, you will often want to run them before they are integrated into an application. You can run a form from the list of forms in Object Designer. To do this, select the form and then click Run. To run forms from inside Form Designer, click File, and then click Run.

See Also

Concepts

Creating Forms


Designing Forms

Designing Forms

This section describes designing the layout of forms in Microsoft Dynamics NAV.

In This Section

Documentation | Description
Working with Controls | This topic describes the work involved in creating controls for forms.
Working with Properties | This topic describes the different properties for forms and controls in Microsoft Dynamics NAV.
Using Controls in Applications | This topic illustrates the different options for using controls on forms.

See Also

Concepts

Creating Forms
Form Fundamentals


Working with Controls

Working with Controls

This section describes how you work with controls in Microsoft Dynamics NAV.

In This Section

Documentation | Description
Types of Controls | This topic introduces the different types of controls that are available with Microsoft Dynamics NAV.
Creating Controls | This topic describes how to create the different types of controls.
Selecting, Moving, and Adjusting Controls | This topic describes working with controls on forms.
How to: Create Labels | This topic describes how to create labels.
Using the Toolbox | This topic describes how to use the Microsoft Dynamics NAV Toolbox
How to: Use Color Tool and Font Tool | This topic describes how to use the Microsoft Dynamics NAV Color Tool and Font Tool.

See Also

Other Resources

Designing Forms


Types of Controls

Types of Controls

This section contains a brief overview of all the controls that can be added to a form.

Controls

The following list is structured according to the broad categories into which controls can be grouped.

Control type | Description
Static Controls | For more information, see Using Static Controls.
Data Controls | For more information, see Using Data Controls.
Containers | For more information, see Using Containers.
Data Containers | For more information, see Using Containers.
Command Button | A command button is not related to data. It performs an action when the button is clicked, or when ENTER is pressed, or when the SPACEBAR is pressed while the button has the focus.
Menu Button | A menu button can be clicked just like a command button, but it does not perform an action. When you click a menu button, a menu opens containing a number of menu items that you can choose.
Menu Item | The lines in a menu that can be chosen are called menu items. Each menu item resembles a command button because it can perform an action when you click it.
Subform | A subform control is used to display a second form in a control on a form (a main form). This allows the main form to show data from two different tables. For example, the main form could be a card form and show records from a customer table, while the subform could be a tabular form and show details about any purchases the customer has made.

See Also

Concepts

Using Static Controls
Using Data Controls
Using Containers


Using Static Controls

Using Static Controls

Static controls are used to contain and display descriptive or graphical information. You cannot change the contents of static controls at run time.

Static Controls

The following table describes the different types of static controls.

Control | Description
Label | A label is used to display text, most commonly the caption of another control. The label is usually a child of the other control, but labels can also be used as stand-alone controls.
Image | An image control is used for displaying a picture.
Shape | A shape is a graphical element, such as line, circle, or rectangle.

See Also

Concepts

Using Data Controls
Using Containers
Using Other Controls


Using Data Controls

Using Data Controls

Data controls display the value of a C/AL expression, for example, the value of a table field or a variable expression. The simplest expression is the name of a table field or a variable. The valid combinations of data control and data types are specified in the following table.

Control | Valid data types
Check Box | Booleans and BLOBs
Option Button | All, except BLOBs
Text Box | All
Picture Box | Boolean, option, integer, and BLOBs
Indicator | Integer, decimal, date, and time

Data controls must have a relationship to data that is defined as the SourceExpr property.

Text Box Characteristics

The text box control has the following characteristics:

  • The table field is its SourceExpr.

  • The default settings for the Name and Caption properties are the same as the setting for the Name property of the underlying table field.

  • In general, every property that is both a field property and a text box property has the value of the field property in the underlying table as its default value.

  • The text box has a label with a caption that defaults to the caption of the text box.

Note Note

When you add text boxes with labels, it is better to use the Field Menu so that both the naming and the properties are consistent. If the data type of the field is Boolean, a check box is created. For all other data types, a text box is created.

See Also

Concepts

Using Static Controls
Using Containers
Using Other Controls


Using Containers

Using Containers

Container controls are used to group controls together. Some properties of the container overrule the same property in the contained controls. If the container is not editable, then none of the contained controls can be edited, even if they individually have the Editable property set to true.

Containers

The following tables describe the types of containers.

Container | Description
Frame | A frame is simply a rectangle into which other controls can be “dropped”. In Form Designer, the frame and the controls that it contains can be moved together. A frame can have different border styles and colors than the form that it is part of.
Tab Control | A form is similar to a book, in that it contains several pages or frames. Only one of these pages is visible at a time. You can switch between the pages by clicking the tabs.

Data Containers

Data container | Description
Table Box | A special kind of container that holds repeated data controls and is used to create columnar tables. Each data control contained by the table box constitutes one column for which a static control is used as a heading. The rows are created by vertically repeating each data control. If the table box displays records from a table, each row displays one record.

See Also

Concepts

Using Static Controls
Using Data Controls
Using Other Controls


Using Other Controls

Using Other Controls

This topic briefly describes some of the other controls that are available when working with forms.

Command Button

A command button is not related to data. It performs an action when the button is clicked, or when ENTER is pressed, or when the SPACEBAR is pressed while the button has the focus.

Menu Button

A menu button can be clicked just like a command button, but it does not perform an action. When you click a menu button, a menu opens containing a number of menu items that you can choose.

Menu Item

The lines in a menu that can be chosen are called menu items. Each menu item resembles a command button because it can perform an action when you click it.

Sub Form

A subform control is used to display a second form in a control on a form (a main form). This allows the main form to show data from two different tables. For example, the main form could be a card form and show records from a customer table, while the subform could be a tabular form and show details about any purchases the customer has made.

See Also

Concepts

Using Static Controls
Using Data Controls
Using Containers


Creating Controls

Creating Controls

This section describes how to work with creating controls on forms.

See Also

Tasks

How to: Add a Text Box
How to: Add a Text Box without Using the Field Menu
How to: Create a Frame to Contain Controls
How to: Create a Tab Control
How to: Create a Table Box


How to: Add a Text Box

How to: Add a Text Box

If the text boxes that you want to add to the form are related to database table fields, the easiest way to add them is to use the Field Menu. The Field Menu is a window that lists all the fields in the table that have been defined as the Source Table for the form. To open the Field Menu in Form Designer, click View, and then clickField Menu.

To add a text box

  1. Open Form Designer.

  2. Create a blank form based on the Customer table.

  3. Click View, and then click Field Menu to open the Field Menu window.

  4. In the Field Menu window, select the field or fields that you want to place on the form.

  5. Move the cursor into the design area to change the cursor into the Control Insertion cursor. You do not have to drag and drop; just select the fields and move the cursor.

  6. In Form Designer, click once to activate the designer and click again to insert the text boxes.

See Also

Tasks

How to: Add a Text Box without Using the Field Menu
How to: Create a Frame to Contain Controls
How to: Create a Tab Control
How to: Create a Table Box


How to: Add a Text Box without Using the Field Menu

How to: Add a Text Box without Using the Field Menu

Although the easiest way to add a text box is by using the Field Menu, you can add text boxes without using the menu. This is the method you use when you want to add a calculated text box, that is, a text box that is used to display a calculated value.

To add a text box without using the field menu

  1. Open the form in the Form Designer.

  2. Open the Toolbox and select the Text Box tool.

  3. Move the cursor into the design area.

  4. Click to add a text box of the default size, or click and drag to create a text box with a different size.

See Also

Tasks

How to: Add a Text Box
How to: Create a Frame to Contain Controls
How to: Create a Tab Control
How to: Create a Table Box


How to: Create a Frame to Contain Controls

How to: Create a Frame to Contain Controls

A frame is used to contain other controls. When controls are contained in a frame, you can perform some operations on all these controls during design. For example, the controls are all moved when the frame is moved with their relative positions intact and if the frame is invisible all the contained controls are also invisible. A frame can have a border that can be raised or lowered. This feature can be used to visually distinguish a group of controls such as a group of option buttons.

To create a frame with contained controls

  1. Open the form in Form Designer.

  2. Select the Frame tool, click and drag in the design area to create a frame.

  3. Create the controls that you want to contain in the frame by placing them inside the frame.

  4. Set the properties of the frame to suit your needs.

    Note Note

    A common change is to remove the caption display by setting the ShowCaption property to No. By default, the border style is Raised. If the frame's purpose is not to distinguish the contained controls, set the Border property to No, so that the border is not displayed.When you drag and drop an existing control inside a frame, it is contained in the frame. When a control is dragged outside a frame, it is no longer contained by the frame. If a container is resized and then overlaps the existing controls completely, these controls will be contained by the frame. If a frame is deleted, all the contained controls are also deleted.

See Also

Tasks

How to: Add a Text Box
How to: Add a Text Box without Using the Field Menu
How to: Create a Tab Control
How to: Create a Table Box


How to: Create a Tab Control

How to: Create a Tab Control

A tab control is useful when you are designing a form that is based on a table with several fields. Instead of creating a large form cluttered with controls, you can group controls together on pages that the user can bring forward by clicking the tabs. You can use a form wizard to create a form with a tab control.

To create a tab control

  1. Open the form in Form Designer.

  2. Select the Tab Control tool and drag and drop in the design area to create a tab control.

  3. Open the Properties window for the tab control, and create the pages that you need by entering a name for each page as a comma-separated list in the PageNames property. The names are used as captions on the tabs.

See Also

Tasks

How to: Add a Text Box
How to: Add a Text Box without Using the Field Menu
How to: Create a Frame to Contain Controls
How to: Create a Table Box


How to: Create a Table Box

How to: Create a Table Box

You can use a text box to display many records from a database table at the same time. A table box contains columns and rows, and you can move through the records either by using the vertical scroll bars or by using the arrow keys or PAGEUP and PAGEDOWN. If the form is too narrow to display all the columns, a horizontal scroll bar is automatically added to the control. You can use a form wizard to create a form with a table box.

To create a table box

  1. Open the form in Form Designer.

  2. Open Toolbox and select the table box tool.

  3. Drag and drop in the design area to create a table box.

  4. Set the SourceTable property of the form to the name of the table that you want to use.

  5. Click View, and then click Field Menu to open the Field Menu window.

  6. Select the fields that you want in the table box from the Field Menu and click twice inside the table box. The first click activates Form Designer and the second click inserts the fields. A column is added for each field, and each row will display a record from the table. A label, derived in the same way as a label for any text box, is added as a column heading.

See Also

Tasks

How to: Add a Text Box
How to: Add a Text Box without Using the Field Menu
How to: Create a Frame to Contain Controls
How to: Create a Tab Control


Selecting, Moving, and Adjusting Controls

Selecting, Moving, and Adjusting Controls

This section describes how to select and move controls, and how to adjust controls by aligning and sizing them.

Selecting Controls

Before you can move or adjust a control, you must select it. While some operations can be applied to only one control at a time and others to a group of controls, controls can be selected both individually and as groups. You select a control by clicking on it. To make it easier to see what the mouse cursor is pointing to, the appearance of the cursor changes as it is moved around the design area. When the cursor points to a control, it becomes a selection cursor. Clicking the mouse selects the control, which is then surrounded by a box with sizing handles.

Multiple Selections

A multiple selection is a group of controls that are all selected. You make a multiple selection, for example, to align all the controls in the selection (how to align the controls is described later).

Adding to a Selection

When one control has been selected, you can add other controls to the selection by holding down the CTRL key and then selecting the other controls. As you select more controls, a box appears around the complete selection and each control in the selection is marked by a circle in the upper left corner of its own bounding box.

Marquee Selection

Another way to make a multiple selection is to use marquee selection. When the mouse cursor is in the design area but not pointing at anything, press the left mouse button and hold it down. Then drag the mouse and a rectangle appears. This is called a marquee. As the rectangle expands, any control that it overlaps, completely or partially, is selected and a circle appears in the upper left corner of its bounding box. Release the mouse button when you have selected all the controls that want. Controls can be added to the selection individually (as described earlier), and a marquee selection can be added to an existing selection by holding down the CTRL key while you carry out the marquee selection.

Note Note

There is an option that determines how marquee selection works. Click Tools, and then click Options. In the Options window, the Marquee Full Selection option can be set to Yes or No. If the option is set to No, the marquee selection works as described earlier. If it is set to Yes, a control is only selected if the marquee overlaps the control completely—not just partially.

Selection and Container Controls

When you select a container control, all the controls that it contains are selected, even if they are not marked by individual bounding boxes. Be aware that a contained control can be moved so that it is only partly inside the container. However, it is considered part of the control as long as any part of it overlaps the container. To select such a control, you must click in the part that is still inside the container.

Selection and Control Branches

A control branch consists of the control itself and one or more child (subordinate) controls. An example is a text box with a label. Both are controls—the text box holding information that can change during program execution and the label holding static information (usually a caption for the text box), changeable only during form design. The label is said to be a child of the text box. When a control branch, such as a text box with a label, is selected, the control itself is displayed in a bounding box with sizing handles, as usual. The child controls that are part of the control branch are marked by a box with a circle in the upper left corner, and the whole branch is surrounded by a dotted emphasis frame. If you click the emphasis frame (the cursor changes into a selection cursor as it touches the frame), the child controls are added to the selection; this turns the selection into a multiple selection that can be moved as a whole.

Moving Controls

When the selection cursor appears, you can move the control below it by pressing the left mouse button and holding it down while you drag the control to the desired position. The control is dropped when you release the mouse button.

Moving Selected Controls

Controls also can be moved after they have been selected. To move a selected control, move the mouse cursor toward it. When the cursor touches the border of the control, it looks like a hand. Press and hold down the left mouse button, drag the control to the desired position, and then release the mouse button. Multiple selections are moved as a whole and their relative positions within the selection are not changed.

Aligning Controls

If you created a form without using a wizard, or if you did use a wizard but rearranged some controls afterward, you may want to align the controls more precisely. There are two methods for aligning controls easily and accurately in C/SIDE:

  • To turn on the Snap to Grid option, click Format, and then click Snap to Grid. When you move a control it does not move smoothly, but in small, fixed increments. The dots in the design area represent some of the actual grid points that the controls snap to when they are moved. The distance between the grid points are properties (HorzGrid and VertGrid) of the form. The unit is 1/100 millimeters.

  • To align several controls, make a multiple selection of the controls and click Format, and then click Align. In the submenu that appears, select one of the four ways to align the controls. If, for example, the controls are in a column, you will want to align them vertically, either to the left or to the right. Select Left or Right to do this. Correspondingly, a row of controls can be top or bottom aligned. Be aware, however, if you inadvertently choose to top align a column of controls, all the controls will be placed on top of each other.

Sizing Container Controls

If you have created a container control, you can size the contained controls individually in the usual manner. The containing control—for example, the frame—can be sized like any other control. When a containing control is sized, the contained controls are not affected, that is, neither their size nor their position changes.

When you enlarge a container, any control that becomes completely overlapped by it will automatically be 'adopted' as a child that is contained by the container control. You should also be aware that you can reduce the size of a container control so that a control that it contains seems to be outside the container. However, this control is still considered to be part of the container. If no part of the control is inside the container control, it cannot be selected. You will need to enlarge the container so that all the contained controls are inside it. For more information, see How to: Size and Resize Controls.

See Also

Tasks

How to: Size and Resize Controls

Concepts

Types of Controls
Creating Controls


How to: Size and Resize Controls

How to: Size and Resize Controls

When the form wizard adds controls to a form, these controls are sized evenly according to a default scheme. If you move the controls around, the sizes that the wizard assigned may no longer be appropriate. Other situations where you might want to change the size of a control are if you change the font size, or if you do not want to display all the information from a large table field, but only the first part. You can only resize one control at a time.

To size and resize controls

  1. Select the control. It is now surrounded by a bounding box with sizing handles.

  2. Select a sizing handle and the cursor becomes a sizing cursor.

  3. Click the left mouse button and drag the control until it has the size you want. If the Snap to Grid property is set, the sizing takes place in fixed increments.

See Also

Concepts

Selecting, Moving, and Adjusting Controls


How to: Create Labels

How to: Create Labels

You can add a label that is not the child of another control to a form. You can do this if you want to have descriptive text on the form, such as instructions about using the form or other static information that is not related to any database table field.

To add a label

  1. In Form Designer, open a form.

  2. Open the Toolbox and select the Label tool.

  3. Move the cursor into the design area.

  4. Click to create a label of the default size, or use a drag-and-drop operation to create a label of a different size.

See Also

Other Resources

Working with Controls


Using the Toolbox

Using the Toolbox

The Toolbox is used to insert controls on a form.

The Toolbox

To open the Toolbox, click View, and then click Toolbox, or click the Toolbox button on the toolbar. To select a specific tool, click the corresponding icon in the Toolbox. You use the Pointer tool to select controls on a form in Form Designer. If you select any of the other tools, the cursor changes from a selection tool to an insertion tool. Usually, after you insert a control, you must select the control again in the Toolbox before inserting the next control. However, the Lock tool maintains the current control selection and you can continue inserting controls of the same type without having to select the control again in the Toolbox. If the Add Label tool is also selected, all the controls that you add to the form are given a label when you insert them.

See Also

Tasks

How to: Add a Text Box

Concepts

Types of Controls


How to: Use Color Tool and Font Tool

How to: Use Color Tool and Font Tool

In addition to the Properties window, you can use two special tools to set some of the properties of controls:

  • Color tool, for selecting color properties and border styles.

  • Font tool, for setting font properties.

To use Color Tool

  1. Click View, and then click Color to open Color Tool.

  2. Open the Property window for the selected control.

  3. To select colors for foreground, background, and border, click the palette.The corresponding properties are ForeColor, BackColor, and BorderColor.

  4. Use the Background and Border check boxes to display the selected color.

  5. In the Property window, set the BackTransparent property and Border property to Yes to display the selected color.

  6. If the control has a border, select the style and width using one of the buttons at the bottom of the window.

To use Font Tool

  1. Click View, then click Font to open Font Tool.

  2. Select a control that displays text.

  3. Enter the name of the font to use.

  4. Enter the font size for the selected font.

  5. Click the buttons at the bottom to select font attributes and alignment.The General button aligns text to the left and numbers to the right.

See Also

Concepts

Working with Properties

Other Resources

Working with Controls


Working with Properties

Working with Properties

Properties are a system-wide feature and every application object has some properties. This topic provides information about properties for forms and controls, and how properties are inherited.

Form and Control Properties

To edit form and controls properties, open the Properties window in Form Designer. As you select a form or control, the Properties window displays the properties of the selected object. The title bar of the Properties window shows which kind of object, such as form, text box, or label is currently selected. The first line in the window shows the ID of the object.

Each line in the Properties window contains a property which you can set in the Value field. If your entry contains an error, the update is not accepted. The default values are displayed in angle brackets. If a property has a default value, you can reset it by deleting the current value and then moving out of the field. Some properties do not have default values—mainly those that describe the position of the control within the form. These properties are updated by C/SIDE when the control is moved.

How Properties are Inherited

Controls that have a direct relationship to table fields inherit the settings of those properties that are common to both the field and the control. You can change the settings of these properties for the control, but you cannot overrule the settings of the field properties that concern data validation. For example, if the field property that determines which characters the user can enter is set to lowercase only, you cannot use the properties of the control to reset it to also accept uppercase characters. You can narrow the accepted range of characters but not broaden it. However, you can change properties like the caption because this property has nothing to do with data validation. When you design an application, you must consider whether these common properties should be specified at the field level or the control level. The advantage of using the lowest level (the field level) is that it ensures consistency because when the field is used as the data source of a control, these settings are used as the default.

See Also

Other Resources

Working with Controls


Properties for Forms

Properties for Forms

This topic lists some of the most commonly used form properties.

Form Properties

The following table briefly describes the form properties.

Property name Description

ID

Sets the numeric ID of the object. This property can also be set when you save a form. The ID must be unique among forms. Your Microsoft Certified Partner can tell you the number range that you can use.

Name

Gives the form a descriptive name. No two forms can have the same name.

Minimizable

Specifies whether you can minimize the form window.

Maximizable

Specifies whether you can maximize the form window.

Sizeable

Specifies whether you can resize the form window.

SavePosAndSize

Specifies whether information about the user-made changes to the size and placement of a form window are saved.

If set to Yes, this information is saved, and the next time the window is opened, these values are used. Otherwise, the designed values are used.

Editable

Specify whether you are allowed to edit controls in the form. If it is set to No, controls may not be edited, even when their individual Editable properties are set to Yes.

InsertAllowed

Specifies whether the form can be used to insert records in the database.

ModifyAllowed

Specifies whether the form can be used to modify records in the database.

DeleteAllowed

Specifies whether the form can be used to delete records from the database.

CalcFields

Specifies a list of FlowFields that you want to use to calculate when the form is updated. If the FlowField is a direct source expression, it is automatically calculated. However, if it is indirect (part of an expression) it is not automatically calculated.

UpdateOnActivate

Specifies whether you want the form to be updated when it is activated.

SourceTable

Specifies the source table of the form.

Usually, you specify the table when you first create the form. If you have created a form without an underlying table, you can enter a table name here to bind the form to a table.

SourceTableView

Creates a view (what you can see) of the source table for this form. You can specify the key, sort order, and filter.

SaveTableView

Specify whether information will be saved about which record the user is viewing when the form is closed, the sort order, and the current filter, and then reapplies this information when the form is opened again.

See Also

Concepts

Working with Properties

Other Resources

Designing Forms


Properties for Controls

Properties for Controls

This topic lists the properties that are common to several types of controls.

Control Properties

The following table briefly describes the control properties.

Property name | Description
ID | Sets the numeric ID of the control. A sequential number is assigned by default. If you delete a control, and then add another in its place, you may want to give the newly created control the number of the one you deleted. The ID must be unique among controls and menu items on the form.
Name | Gives the control a descriptive name.
Caption | Specifies the text that is displayed for this control.
HorzGlue | Anchors a control horizontally on the form. You can select Left, Right, or Both. If you select Both, the control is resized when the form is resized.
VertGlue | Anchors a control vertically on the form. You can select Top, Bottom, or Both. If you select Both, the control is resized when the form is resized.
Visible | Specifies whether the control is visible when the form is opened. This property can be changed from C/AL at runtime. Notice that if the control is a child control and the parent has Visible set to No, the child will not be visible, even if Visible is set to Yes.
ParentControl | Specifies the ID of a parent control, thereby turning the control into a child.

See Also

Concepts

Working with Properties
Properties for Forms

Other Resources

Working with Controls


Changing the Properties of a Control

Changing the Properties of a Control

If you add controls without using the form wizards, you often need to change some of the properties of these controls. Even if you did use a wizard, you may want to change some of the properties to meet specific requirements that the wizards cannot provide.

Changing the Name and Caption of a Control

Every control has an ID and a Name. Controls that display data also have a SourceExpr property which is a C/AL expression. This can just be the name of a table field name or it can be a complex expression, perhaps with a field as an operand. When you use a form wizard or the Field Menu to create a text box that has a direct relationship to a table field, the Name and Caption are set by default to the name of the table field (unless the table field has a Caption, in which case this Caption is used). The label has a Caption derived from the Caption of the parent control (the text box). You can supply a Caption in either place if you want to have a different, perhaps more descriptive text than the field name as a caption. Be aware of the following dependencies:

  • If you change the Caption property of the text box, the Caption property of the label is set to this value as a default (displayed in angle brackets). If you change the text box Caption property again, the Caption property of the label is also changed again.

  • If you change the Caption property of the label directly, the value you enter is displayed without angle brackets, signifying that it is no longer a default value. Now if you change the property of the text box again, the value here is not updated.

Changing an Unbound Control into a Bound Control

An unbound text box, or other data control, can be easily changed to a bound control. You need to change the SourceExpr to the one that you want. If it is the name of a field in the database table, the values for Name and Caption automatically default to the standard values of the bound control, that is, they default to the name of the table field. This will not automatically add a label to the text box. If you want to change the source expression so that it refers to a field from another table, you must enter a more complex C/AL expression.

Adding a Label to a Text Box

If you create a bound text box by changing the SourceExpr of an unbound text box, the bound text box does not automatically get an attached label. You can add a label by adding a label control to the form and then changing the ParentControl property of the label from the default (undefined) to the ID of the text box. You can see the ID of the text box in the first line of the Properties window for the text box. The control branch resulting from this operation can be selected and moved like other controls.

See Also

Concepts

Working with Properties
Creating Controls

Other Resources

Working with Controls


Display Properties

Display Properties

Controls that you add to a form—either by using a wizard or manually—have a default set of properties that define how the control and the data it displays are formatted. While this ensures a consistent visual design throughout your application, it cannot cover all your needs. You may need to change some properties that affect the way your forms and their controls are displayed.

Controlling the Display of Numbers

The following table shows how properties determine the way numbers are displayed.

Property name | Description
DecimalPlaces | This property (that specifies both the minimum and maximum allowed values) determines how many decimals are displayed, as well as how many decimal places can or must be entered. A typical situation where you would use this property is when amounts are stored in the database with 5 decimal places for high precision but you only want to see the customary number of decimal places for the currency, for example 2. The table field would then have the DecimalPlaces property set to 2:5, while the + property of the text box is set to 2:2.
BlankNumbers | You can select from an option list whether a range of numbers will be displayed.
BlankZero | The default is No. If you change it to Yes, zero values and Booleans that would have been displayed as a No are not displayed.
Divisor | The default is Undefined. If a number is entered, numeric values are divided by this number when they are displayed. Any remainder is discarded. You could, for example, use the Divisor property to display only the thousands part of a number by entering 1000 (then 16400 and 16800 would each be displayed as 16).

Formatting Data Display

The following table shows how the properties determine the way data is formatted.

Property name | Description
Format | This property defines how to format the SourceExpr of a text box. For each data type, there is a default. There is also a set of standard formats that you can select. You can also build your own formats if needed.
HorzAlign and VertAlign | These properties define how data in a text box or a caption on a label is aligned horizontally and vertically.
MultiLine | This property determines whether labels and text boxes can contain multiple lines of text. The default is No with one exception; the label of a column in a table box will have this property set to Yes.
PadChar | This property specifies the character that should be used to pad a string. The character will be added to the left or right, or both, depending upon the text alignment defined by the HorzAlign property.
LeaderDots | This property specifies whether there are leading dots before the data. The dots are placed according to the data's horizontal alignment. If the data is left aligned, the dots are placed on the right and if it is right aligned, dots are placed on the left. If centered, there are dots both before and after the data. If this property is set to Yes, the PadChar setting is overruled.

See Also

Concepts

Working with Properties
Properties for Forms


Properties that Control Input

Properties that Control Input

Properties that control input is a group of properties used to control user input. This means that these properties restrict user input to certain values or a certain length.

Properties

The following table shows properties that control input.

Property name | Description
Numeric | Restricts input to numeric values only if it is set to Yes.
MinValue, MaxValue | Sets a minimum or maximum value that you can enter.
ValuesAllowed | Specifies the values that you are allowed to enter. Enter the values separated by semicolons, such as 1;7;4711 or a;b;c.
CharAllowed | Specifies the characters that you can enter. You can use a range, for example AZ, to limit entry to uppercase characters only, or several ranges, for example amot, specifies two ranges: a to m and o to t.
NotBlank | Specifies whether an entry can be blank. If this property is set to Yes, an entry that consists of nothing, one blank space or several blank spaces is not accepted. A blank can be part of string that contains other characters.
MaxLength | Specifies the maximum number of characters that can be entered in a text box.
AutoEnter | If set to Yes, entries are accepted when the maximum number of characters allowed has been entered into a table box, and it will then move the focus to the next control – that is, you do not have to press ENTER.
PasswordText | Specifies whether your input is displayed as text. If this property is set to Yes, your input is not displayed but shown as asterisks (******).

See Also

Concepts

Working with Properties
Creating Controls

Other Resources

Working with Controls


Assisting the User

Assisting the User

Properties that assist the user are a group of properties that is used to provide the user with help. If the Status Bar option is set to Yes, the caption of text boxes and check boxes is displayed in the status bar together with the current data contents of the control (if any) when the control gets the focus. To set the Status Bar option to Yes, click Tools, and then click Options.

Properties

The following table shows how properties can be used provide the user with help. .

Property name Description

ToolTip

This property allows you to display text that describes a control. If you enter a text for this property, it is displayed in a small pop-up window when the user holds the cursor over the control. The text should be a short, perhaps just one word, description of what the control is used for.

DataCaptionField, DataCaptionExpr

This property controls the label that is displayed on the title bar of the form window. This is a static caption, usually the name of the underlying table.

By using DataCaptionField (either at the table or form level), you can select fields from the record whose contents are displayed (and updated) in the caption bar as you page through the table. With DataCaptionExpr (only on forms) you can create a C/AL expression to be displayed in the caption bar. The expression is reevaluated when you select a new record or the present record is changed.

See Also

Concepts

Working with Properties

Other Resources

Working with Controls


Using Controls in Applications

Using Controls in Applications

This section describes methods that you can use to control the way data is displayed in your applications.

See Also

Tasks

How to: Display More Than One Line of Text
How to: Display a Calculated Value
How to: Create a Drop-Down List of Options
How to: Create an Option Button Group
How to: Use a Check Box to Display Booleans
How to: Create Command Buttons
How to: Contain Controls Within a Frame
How to: Use an Indicator to Display Values

Concepts

Adding Shapes and Pictures


How to: Display More Than One Line of Text

How to: Display More Than One Line of Text

If a database table contains large fields with lengthy content, then using the standard one-line text box is not the best way to present this information. Instead, you can customize a text box so that it wraps text into multiple lines.

When you enter or edit text, the line scrolls horizontally. When focus is not on the text box, the contents of the field will be formatted in multiple lines. Automatic line breaks occur only after a space, and you can insert line breaks ("hard newlines") by embedding a backslash character ("\") in a text string. To display a backslash, enter "\\".

To display more than one line of text

  1. Open the form in Form Designer.

  2. Select the text box and enlarge it vertically by resizing.

  3. Open the Properties window for the text box and set the value of the Multiline property to Yes.

  4. Run the form.

See Also

Tasks

How to: Display a Calculated Value
How to: Create a Drop-Down List of Options
How to: Create an Option Button Group
How to: Use a Check Box to Display Booleans
How to: Create Command Buttons
How to: Contain Controls Within a Frame
How to: Use an Indicator to Display Values


How to: Display a Calculated Value

How to: Display a Calculated Value

A control can display a value that is not stored in the database but calculated as the form is displayed. This is useful when all the information needed for the calculation is stored in the database and the calculated value is not stored separately.

However, the users of the application sometimes need this value. Adding a calculated control can provide this information without violating the rules for good database design. For example, if you have a table with a field that contains the unit price of an item, and another field that contains the employee discount rate. On the form, you want to see the price that an employee has to pay. To do this, add an unbound text box and as its SourceExpr property add the following statement: "Unit Price" - ("Unit Price" * "Employee Discount Rate" / 100). This will display the price that the employee has to pay as a calculated value.

To display a calculated value

  1. Open the form in Form Designer.

  2. Select a tool that inserts an appropriate data control, for example, Check Box, Text Box, or Indicator in the Tool Box.

  3. Click twice in the design area to add the control.

  4. Open the Properties window for the control. Type the expression that you want as the SourceExpr property.

See Also

Tasks

How to: Display More Than One Line of Text
How to: Create a Drop-Down List of Options
How to: Create an Option Button Group
How to: Use a Check Box to Display Booleans
How to: Create Command Buttons
How to: Contain Controls Within a Frame
How to: Use an Indicator to Display Values


How to: Create a Drop-Down List of Options

How to: Create a Drop-Down List of Options

Providing the user with a fixed set of options to choose from in a field is a recurring task in application programming. For example, in a field where the user frequently has to enter the title of a contact, providing a list of titles helps the user. You can only enter options that have been defined in the Properties window of the field or variable. The first option is displayed in the text box. If the OptionString property has a blank as the first option, the text box is blank. In the OptionString property of the control, you can select a subset of the options already defined for the field, but you cannot add options.

In the following procedures, the first procedure explains how to create a card type form that you need to create the drop-down list. The second procedure explains how to create the drop-down list of options.

To create a card type form

  1. Open Object Designer, click Form, and click then New to open the New Form window.

  2. Create a Card-Type Form based on the Contact table and click OK.

  3. In the Card-Type Form Wizard, click the No, I want a plain form option, and then click Next.

  4. Add the following fields to the form: No., Name, Address, Phone No., and Company No.

  5. Click Finish and in Form Designer, expand the form and the container control.

  6. Add a new text box and a label.

To create a drop-down list of options

  1. Select the text box that you just created and open the Properties window.

  2. In the Caption field, enter Organizational Level. The field or variable that is the SourceExpr of the control must be of the Option data type, and the options must be entered as the OptionString property of the field or variable. In this example you will use a variable.

  3. Click View, and then click C/AL Globals to open the C/AL Globals window.

  4. Create a variable called Organizational Level of data type Option and open the Properties window for this variable.

  5. In the Value field OptionString property, enter the following list: Chief Executive Officer,Chief Financial Officer, Junior Manager,Manager,Salaried Employee,Senior Manager. These are the values that are currently available in the Organizational Levels table.

  6. Open the Properties window of the text box and bind it to the variable. To do this, click the AssistButton in the Value field of the SourceExpr property to open the C/AL Symbol Menu window.

  7. Ensure that the Paste Arguments option is active, select Organizational Level, and then click OK.

  8. Save and compile the form.

See Also

Tasks

How to: Display More Than One Line of Text
How to: Display a Calculated Value
How to: Create an Option Button Group
How to: Use a Check Box to Display Booleans
How to: Create Command Buttons
How to: Contain Controls Within a Frame
How to: Use an Indicator to Display Values


How to: Create an Option Button Group

How to: Create an Option Button Group

You can present a set of options either by using a drop-down list or by using an option button group. The functionality of the option button is the same as that provided by a drop-down list, but the visual presentation is different. The advantage of using an option button group is that the user of the application can see all the available options and the current option at a glance. The disadvantage is that an option button group takes up more space on the form than a drop-down text box.

To create a card type form

  1. Open Object Designer, click Form, and then click New to open the New Form window.

  2. Create a Card-Type Form based on the Contact table and click OK.

  3. In the Card-Type Form Wizard, click the No, I want a plain form option, and then click Next.

  4. Add the following fields to the form: No., Name, Address, Phone No., and Company No.

  5. Click Finish and expand the form and the container control in Form Designer.

To create an Option Button Group

  1. In Form Designer, open the form that you created earlier.

  2. Open the toolbox and add a frame to the form.

  3. Open the Properties window and enter Organizational Level as Caption.

  4. Set the BorderStyle property to BumpUp.

  5. In the new frame, add six control buttons, one for each of the options available in the Organizational Levels table.

  6. In the Properties window for each option button, enter "Organizational Level Code" as the value in the SourceExpr field. Remember to enter the quotation marks.

  7. In the Caption field, enter the six values that are currently available in the Organizational Level Code table.

  8. In the OptionValue property for each button, enter the corresponding value from the Organizational Level Code table.

  9. Save and compile the form.

See Also

Tasks

How to: Display More Than One Line of Text
How to: Display a Calculated Value
How to: Create a Drop-Down List of Options
How to: Use a Check Box to Display Booleans
How to: Create Command Buttons
How to: Contain Controls Within a Frame
How to: Use an Indicator to Display Values


How to: Use a Check Box to Display Booleans

How to: Use a Check Box to Display Booleans

A check box control is an easy way to display data of type Boolean. In a text box, Boolean values will be shown as Yes and No. The check box is selected to indicate Yes and it is clear to indicate No.

To use a check box to display Booleans

  1. Open the form in Form Designer.

  2. If the check box will have a direct relationship to a table field, select the field in the Field Menu, Otherwise create an unbound check box.

  3. Click the Add Label tool if you want a label attached to the check box.

  4. Choose the Check Box tool, and then click in the design area to create the check box.

  5. Bind the check box to a variable if it is unbound. To do this, enter the name of the variable as the SourceExpr of the text box.

See Also

Tasks

How to: Display More Than One Line of Text
How to: Display a Calculated Value
How to: Create a Drop-Down List of Options
How to: Create an Option Button Group
How to: Create Command Buttons
How to: Contain Controls Within a Frame
How to: Use an Indicator to Display Values


How to: Create Command Buttons

How to: Create Command Buttons

Command buttons are useful for a number of purposes. If you have used a wizard to create forms, you will notice that a Help button has been added to all forms. Other common uses are Yes and No buttons where the user must decide whether a certain task will be performed. Command buttons also launch forms, or even another program.

To create a command button

  1. Open the form in Form Designer.

  2. Select the Command Button tool and click in the design area to add the command button. The next step is to define the action associated with the button.

  3. Open the Properties window for the command button. The PushAction property specifies what happens when the user clicks the command button.

  4. Open the drop-down list in the PushAction property value field. You will see a list of possible actions.

  5. In the drop-down list, select RunObject.

  6. In the RunObject property, open the look-up table of system objects, and choose the object that you want to run when the command button is clicked.

See Also

Tasks

How to: Display More Than One Line of Text
How to: Display a Calculated Value
How to: Create a Drop-Down List of Options
How to: Create an Option Button Group
How to: Use a Check Box to Display Booleans
How to: Contain Controls Within a Frame
How to: Use an Indicator to Display Values


How to: Contain Controls Within a Frame

How to: Contain Controls Within a Frame

A frame is used for containing other controls. When controls are contained in a frame, you can perform some operations on these controls as a whole. For example, during the design process, controls move when the frame moves, with their relative positions intact. If the frame is not displayed to the user, all the contained controls are not displayed either.. A frame can have a border that can be raised or lowered. This feature can be used to visually distinguish a group of controls, such as a group of option buttons.

You can hide the caption form by setting the ShowCaption property to No. By default, the border style is Raised. If you do not want to distinguish the contained controls, you can set the Border property to No, and no border is displayed.

When you use a drag-and-drop operation to move an existing control inside a frame, it is contained by the frame. When you use drag-and-drop to move a control outside a frame, it is no longer contained by the frame.

If a container is resized and overlaps some existing controls completely, these controls become contained. If a frame is deleted, all the controls that it contained are deleted.

To create a frame with contained controls

  1. Open the form in Form Designer.

  2. Open the Toolbox and select the Frame tool.

  3. Click and drag in the design area to create a frame.

  4. Create the controls that you want to contain in the frame in the usual way, placing them inside the frame just as you would add them to the form.

  5. Set the properties of the frame to suit your needs.

See Also

Tasks

How to: Display More Than One Line of Text
How to: Display a Calculated Value
How to: Create a Drop-Down List of Options
How to: Create an Option Button Group
How to: Use a Check Box to Display Booleans
How to: Create Command Buttons
How to: Use an Indicator to Display Values


How to: Use an Indicator to Display Values

How to: Use an Indicator to Display Values

The indicator control allows you to display values graphically, as an analog gauge. A minimum and a maximum value must be defined, so the scale of the indicator can be calculated. If you do not provide these values, default values will be used.

To create an indicator

  1. Open the form in Form Designer.

  2. Select the indicator tool, and click and drag in the design area to create the Indicator.

  3. As the SourceExpr of the Indicator, enter the value that you want to control the indicator.

  4. Set the MinValue and MaxValue properties of the Indicator.

  5. Set the Percentage property to choose whether the indicator will display percentages. If this property is Yes, the % symbol is displayed. The gauge itself is the same when Percentage is No and when it is Yes. (The percentage is calculated as ((value of SourceExpr) – MinValue) / (MaxValue – MinValue))*100).

See Also

Tasks

How to: Display More Than One Line of Text
How to: Display a Calculated Value
How to: Create a Drop-Down List of Options
How to: Create an Option Button Group
How to: Use a Check Box to Display Booleans
How to: Create Command Buttons
How to: Contain Controls Within a Frame


Adding Shapes and Pictures

Adding Shapes and Pictures

You can add graphical elements such as shapes and bitmap pictures to forms. These can be used to emphasize information, by adding a shape that makes some controls stand out—or for purely decorative purposes. The following topics describe how to work with shapes and pictures.

See Also

Tasks

How to: Create a Shape
How to: Add a Static Picture as an Image
How to: Add a Data Bound Picture as a Picture Box

Concepts

Pictures on Buttons and in Check Boxes


How to: Create a Shape

How to: Create a Shape

The ShapeStyle property lets you choose from a number of shapes, such as rectangle, rounded rectangle, oval, and so on. You can adjust the width and color of the lines by changing the BorderWidth and BorderColor properties.

To create a shape

  1. Open the form in Form Designer.

  2. Open the Toolbox and select the Shape tool.

  3. Click and drag in the design area to specify the size of the shape that you want to add. You can adjust it again later.

  4. In the Properties window for the shape, click ShapeStyle and select a shape from the drop-down list.

  5. Use the BorderWidth and BorderColor properties to further refine the design of the shape that you have added to the form.

See Also

Concepts

Adding Shapes and Pictures


How to: Add a Static Picture as an Image

How to: Add a Static Picture as an Image

The simple way to add a bitmap picture to a form is to add it as a control of type image.

To a static picture as an image

  1. Open the form in Form Designer.

  2. Open the Toolbox and select the Image tool.

  3. Click and drag in the design area to create an image control.

  4. Open the Properties window of the image control, and enter the path and name of the bitmap file in the value field of the Bitmap property. The bitmap is imported, so you do not need external files for your application. But if you change the bitmap during development, you must update the imported copy.

  5. To update the bitmap, open the Properties window, select the Bitmap property Value field and press F2. This causes the field to be reevaluated, and forces the bitmap to be imported again. The size of the bitmap cannot exceed 32 KB.

See Also

Concepts

Adding Shapes and Pictures


How to: Add a Data Bound Picture as a Picture Box

How to: Add a Data Bound Picture as a Picture Box

Adding a bitmap in a picture box control instead of in an image control gives you some more advanced possibilities. While the image control is static, the picture box control is dynamic. If you create a list of bitmaps, a bitmap from this list can be chosen at run time (the total size of all the bitmaps in the list can be 32 KB).

One of the other advantages of a picture box is that it can display pictures that are stored in BLOB fields. A BLOB field can have a size of up to 2 GB.

To add a data bound picture as a picture box

  1. Open the form in Form Designer.

  2. Open the Toolbox and select the Picture Box tool.

  3. Click and drag in the design area to create a picture box control.

  4. Open the Properties window for the picture box control.To create a list of bitmaps from which one can be selected at run time for display, enter a comma-separated list of the path and names of the bitmaps that you want to use. Remember that the size of the entire list of bitmaps must not exceed 32 KB. A series of standard bitmaps are provided, which can be chosen by entering a number between 1 and 53. For more information, see BitmapList Property.

  5. The value of SourceExpr determines which bitmap is chosen: the first in the list has number 1, and so forth. If the SourceExpr calculates a value outside the range of bitmaps, no bitmap is displayed.

  6. To display a picture stored in a BLOB field, enter the field name of the BLOB field as the SourceExpr. Do not enter a BitmapList property.


Pictures on Buttons and in Check Boxes

Pictures on Buttons and in Check Boxes

This topic describes using pictures on buttons and in check boxes.

Bitmap Property

Command buttons, menu buttons, option buttons, and check boxes can all display a bitmap picture instead of—or in combination with—a caption.

They all have a property called Bitmap. Here you can enter the path and name of a bitmap. The maximum size of the bitmap is 32 KB. The bitmap is imported, not referenced. This means that if you change the original bitmap, you will have to re-import it.

There is also a property called BitmapPos, which allows you to you select the alignment of the bitmap within the control. This is useful when you combine a caption and a bitmap.

Using a bitmap on a button or a check box can make the interface more intuitive. A well-chosen picture may be easier to remember and identify than a label.

See Also

Concepts

Adding Shapes and Pictures


Extending Forms

Extending Forms

This section describes how you can extend the functionality of forms in Microsoft Dynamics NAV.

In This Section

Documentation | Description
Main Forms and Subforms | This topic describes the work involved in creating subforms for forms.
Looking Up Values and Validating Entries | This topic describes the look up functionality in a form.
Drilling Down to Underlying Transactions | This topic describes how to drill down into underlying transactions from FlowFields.
Opening Another Form | This topic describes how to launch one form from another form.
Designing Menu Buttons | This topic describes how you design menu buttons for forms.
Defining Form and Control Triggers | This topic describes how you define triggers for forms and controls.
Form Types and Characteristics | This topic describes the different form types and what is unique to them.

See Also

Concepts

Creating Forms
Form Fundamentals


Main Forms and Subforms

Main Forms and Subforms

A well-designed database does not store redundant information, but has a number of relationships between tables. The typical relationship is a one-to-many relationship. For example, if you are designing an application that handles sales orders, there can be many items on one single sales order, but one specific item can only be part of one sales order. Some of the information on a sales order, such as the address of the customer, is per order, while other information, such as the item number, is per item. In a well-designed database, with no redundant information, this means that the information on a sales order is stored in two tables: a header table with the general order information and a lines table with the information about each item. There is a one-to-many relationship between the tables. However, users of the application need to view information from both tables at the same time.

The following illustration shows the header and line information.

Although this looks like an ordinary form, it is actually two forms.

The main form is the one side of the one-to-many relationship. In this example, it is based on the Sales Order Header table. The subform is the many side of the relationship and is based on the Sales Order Line table. When you select a sales order header in the main form, the subform is updated to display only sales order lines that are related to this sales order header. There is a link between the main form and the subform to keep the information synchronized.

See Also

Tasks

How to: Design the Main Form

Concepts

Subform Design


How to: Design the Main Form

How to: Design the Main Form

There are no special procedures needed to design the main form in a mainform or subform relationship. To create a subform, you add a subform control. The subform control establishes the link between the main form and the subform, but it is not itself a form. You can, however, display any form in the subform control. If you are going to use an existing form as the subform, follow the procedure described here. If you are going to create a new form to use as the subform, it may be more convenient to create the subform first. For more information, see Subform Design.

Designing the Main Form

To design the main form in a main form and subform relationship

  1. Open the existing form in the Form Designer.

  2. Open the Toolbox, and select the Subform tool.

  3. Click the Subform button, and then click the design area to create the subform control.

  4. Open the Properties window (SHIFT+F4) of the subform control.

  5. In the SubFormID property field, enter the name of the form that the subform is based on (or use the lookup button to select the form from a list).

  6. In the SubFormLink property, enter the expression that links the two tables, for example the field that is common for the tables. There is an assist-edit function available to help you. Click the AssistButton to open the assist-edit window. Select the field name from the many side of the relationship (the subform table). Then select FIELD as the Type of the relationship. Finally, for the Value, select the field from the one side of the relationship (the main form table).

    Note Note

    In the SubFormLink property, you can also select other types of links. If you choose CONST, Value must be a constant expression that selects records where the Field matches this expression. If you choose FILTER, Value must be a filter expression, for example, 10|30..40.

  7. In the SubFormView property, you can specify the key, sort order, and table filter to apply to the table when it is displayed in the subform. (You do not have to enter anything in this property.)

See Also

Concepts

Subform Design


Subform Design

Subform Design

There are no special requirements for a subform. However, you must remember that the form is going to be used to display the many side of a one-to-many relationship, and that all forms are not suitable for this task.

Typically a subform is a tabular form, that is, a form with a table box. The table box should fill out the form completely. The HorzGlue and VertGlue properties of both the table box on the subform and the subform control on the main form should be set to Both. This ensures that the subform and the table box are resized when the main form is resized.

Formatting Subforms

Although creating a form with a subform is the same as creating controls on forms, you may have to experiment before you find the best way to do it.

Here are some hints and advice to help you accomplish this task:

  • It can be difficult to get the correct size of the subform control on the main form and the size of the subform. You should finish the design of the subform first. Get the values for the width and the height of the form from the Properties window of the subform. Then, in the main form, place a subform control of any size. In the Properties window, insert the width and height of the subform as the width and height of the subform control.

  • Generally, if the subform is a tabular form, it looks better if you let the table box completely fill out the form vertically. This ensures that there is no extra space around the table inside the subform control. Set the HorzGlue and VertGlue properties to Both.

  • If the subform is a tabular form, you should set the size of the form so that it only displays a few records at a time. Then, in the main form, set the VertGlue and HorzGlue properties of the subform control to Both. You can resize the main form vertically and horizontally. The subform is resized along with it so that either more or less records and fields are displayed.

See Also

Tasks

How to: Design the Main Form

Other Resources

Working with Controls


Drilling Down to Underlying Transactions

Drilling Down to Underlying Transactions

When a text box is based on a FlowField, a drill-down button (o) is automatically attached to the text box. When you click this button (or press SHIFT+F6), the transactions that are used to calculate the value of the FlowField are displayed.

Example

In the chart of accounts, you can execute a drill-down function in the Net Change field. The FlowField summarizes transactions in this account.

The General Ledger Entries window opens and displays the result of this drill-down.

The drill-down feature is provided when a text box is directly related to a FlowField. To get this feature, you need to define DrillDownFormID, either at the table level or at the form level. For more information about defining the DrillDownFormID, see Defining a Lookup Form in How to: Define the Table Relation.

Drill-downs resemble lookups in many ways, and allow you to do most of the things that you can do with lookups. One exception is that drill-downs only apply to FlowFields, which have to be defined when the table is designed.

Customizing Drill-downs

You can customize a drill-down in the following ways:

  • You can disable the drill-down by setting the DrillDown property for the text box to No.

  • Text boxes based on the same FlowField will have different drill-down forms if you define separate DrillDownFormIDs at the form level.

  • You can decide whether the drill-down button should be displayed permanently or only when the text box has the focus. This is done by setting the PermanentAssist property for the text box. Yes means that the button is always displayed, and No means that the button is only displayed when the text box has the focus.

  • You can change the drill-down behavior by writing C/AL code in the OnDrillDown trigger of the table field or in the control. In this case you have to run a form explicitly from your trigger code.


Looking Up Values and Validating Entries

Looking Up Values and Validating Entries

Usually, the main form is bound to the table on the one side of the relationship, and the subform is bound to the many side of the relationship.

Suppose instead, that you want to design a form that is bound to a table that contains information about customers. Some of this information is unique for each customer, but some of the information is not. The names and addresses of the customers are unique, but perhaps you want to store information about the shipper that is normally used for deliveries to each customer. There are only a few shippers, and it would be redundant and in violation of relational database design rules to store information such as the addresses of these shippers in the customer records.

Instead, you should create a Shipper table, and use a Shipper Code field to create a link between this table and the Customer table. You should only store the shipper code in each customer record in the Customer table and store all the other information about the shippers in the Shipper table.

This is the many side of a one-to-many relationship. Each customer can be associated with only one shipper, but a shipper can be associated with many different customers.

A main form or subform structure is not applicable in this scenario. (Although it would be applicable if you were to design a form to display information about the shippers. The subform could then display a list of the customers that use each shipper.)

Creating the Customer form

There are two things to consider when creating the Customer form (and table):

  • Do you want an easy way to enter the shipper code?

  • Do you want to validate the Shipper Code field in the Customer table against the Shipper table? That is, do you want the system to verify that the contents of the Customer table field are present in the Shipper table?

If you do not establish a relationship to the Shipper table, you will need to remember the shipper codes. This means that you can easily enter a code that does not exist in the Shipper table. If the tables are related, a lookup function is provided for the Shipper table, so that you can press F6 or click a lookup button and select the shipper code from a list that displays the codes as well as other information, such as name and address.

A control can be related to a field in another table in two different ways. The first is by defining the relationship at table level, as a property of the Shipper Code field in the Customer table. The second is by defining the relationship at form level, as a property of the text box that displays the shipper code on the Customer (main) form.

If you want to ensure that you do not enter non-existent shipper codes into the Customer table, you can validate the entries against the Shipper table. The ValidateTableRelation property, either for the field (at table level) or for the text box (at form level), determines whether the values you enter must exist in the Shipper table.

Apart from simply ensuring that the entered codes exist in the Shipper table, you can create more advanced validation rules that check the entered codes against combinations of values for fields in both tables. For example, you can have the system check whether the shipper allotted to a customer operates in the customer's country/region. To do this, you have to create the validation rule by writing C/AL code in the OnValidate trigger of the control on the main form.

See Also

Tasks

How to: Define the Table Relation


How to: Define the Table Relation

How to: Define the Table Relation

The relationship to a table can be defined in two different places—as part of the table description or as part of the form description. In both places, the relationship is defined in the TableRelation property of the field or control. There is no functional difference between a table relationship defined at the table level and a relationship defined at the form level. But there is a difference when you are designing an application. If the relationship is defined at the table level, all the text boxes in the forms that have a direct relationship to the field will automatically have the lookup functionality. You can suppress this function by setting the Lookup property of the text box to No.

Defining the Table Relationship

To define a table relationship

  1. Open the form in the Form Designer.

  2. Open the Properties window (SHIFT+F4) of the field or control.

  3. In the Value field of the TableRelation property, click the AssistButton.

  4. In the Table Relation window, enter the name of the table that you want to look up in the Table field or choose it from the list that appears when you click the look up button.

  5. In the Field field, enter the name of the field in the table (or choose it from the list).

You can use the Condition and the Table Filter fields to create a more advanced relationship.

By using the Condition field, for example, you can look up different tables, depending upon the value of a field in the current table. Each condition line corresponds to a statement in an if…then...else…if sequence.

In the Table Filter field, you can set a filter on the lookup table.

Validating Entries

Entries can easily be validated against the contents of a field in a related table. If you set the ValidateTableRelation property to Yes—either at the field level or at the control level—only entries that exist in the related table will be accepted.

If you need a more advanced validation, you can write C/AL code in the OnValidate trigger of either the control or the field.

Using the Default Lookup or Writing Your Own

If you want more control over how a lookup functions by just using conditions and filters, you can write C/AL code in the OnLookup trigger. This allows you to bypass the default lookup function and write your own.

The following rules determine how a lookup function is performed:

  • A trigger at the form level takes precedence over a trigger at the table level.

  • Triggers take precedence over the system default action.

Defining a Lookup Form

When you are using the system lookup function, you must define which form to use to display the results of the lookup. You can define the form in two ways:

  • Each table can have a form that is used for accessing the table. You can do this by setting the LookUpFormID property of the table.

  • The form can be defined by setting the LookUpFormID property of the control for which the lookup is provided.

If both properties are set, the form that is defined as a control property is used.

If no lookup form is defined either at the table or the form level (although the text box contains a lookup button), a lookup is not performed when the button is clicked. If you are writing a lookup function in the OnLookup trigger, you have to explicitly run a form by using the RUNMODAL C/AL function.

Note Note

If you always design a basic tabular form for a table and enter this form as the LookupForm (and DrillDownForm) for the table. If you later decide that this form is not adequate for some lookups, you can add customized forms as control properties.

Permanent Assist

The PermanentAssist property is a control property. If set to Yes, the lookup button is permanently displayed; otherwise, it is displayed only when the control has the focus.

Looking Up in the Current Table

By setting the Lookup property for a text box to Yes, you can access the source table of the form. This makes it easy for you to select records. In effect, the lookup provides a list of all the records in the table and you can select a record from the list, and this record then becomes the current record.

A lookup form must be defined either at the table or form level in the same way as it must be defined when the lookup is in another table. However, you cannot set conditions and filters as you can when the lookup is in another table. The default behavior is to display all the records in the table. If you need to change this, write your own lookup function in the OnLookup trigger.

If a lookup in a related table is defined—regardless of how the relation is defined—setting the Lookup property to Yes is overridden. But if Lookup is explicitly set to No (as opposed to its default value <No>), no lookups, including to related tables, are performed.

You can provide the same functionality by using the LookupTable action (applicable to command buttons and menu items). You can provide both types of lookup on the same form: lookups to related tables from text boxes, and lookups to the source table from command button actions


Opening Another Form

Opening Another Form

When you use a lookup function to select values in a related table, you typically only display a subset of the fields in the lookup table.

In some situations, however, you may want to update more fields in the related lookup table than are displayed on the lookup form without having to close the current form.

Adding a Control to Open Another Form

If you are taking orders by phone, it is convenient when you can use a lookup function on the sales order form to find the customer numbers as the customers call in.

However, a customer could call in to order something and inform you that they have changed their address. It is time-consuming to have to close the sales order form, select the customer form, find the customer, change the address, and then return to the sales order form to start entering the order again.

A better solution would be to open the customer form directly from the sales order form, automatically select the appropriate customer record, update and close the customer form, and continue filling out the sales order form.

To open another form, you can add a control that has a PushAction property and run the customer form with parameters that select the correct record from the Customer table when you use the assigned control. You can use command buttons, menu items, check boxes, or option buttons.

See Also

Tasks

How to: Add a Command Button


How to: Add a Command Button

How to: Add a Command Button

Use the following procedure to add a command button that launches a form.

Procedure

To add a command button

  1. Add a command button. For more information about adding command buttons, see How to: Create Command Buttons.

  2. Set the PushAction property of the command button to RunObject.

  3. Set the RunObject property of the command button to the name of the form that you want to launch. Because you can use RunObject to run any object, you must specify the type of object, such as Form or Codeunit. You can choose the object from the lookup list provided (in this case, the type of the object is inserted automatically).

  4. Set the RunFormLink property to establish the link to the form that you want to launch. Use the assist-edit button to create the expression. In the Field field, select a field from the form source table. In the Type field, select FIELD as the type of relationship. Finally, in the Value field, select the field from the source table that triggers the current form. This field must match the field that you selected from the source table earlier.

See Also

Concepts

Programming Guidelines for Functions in Forms


Designing Menu Buttons

Designing Menu Buttons

Although command buttons are a convenient way to add functionality to forms, having too many buttons on a form can create clutter and detract from the usability and visual design. If you have to add many command buttons to a form, you should consider creating a few menu buttons instead. When you click a menu button, a menu opens.

Menu Items

Each line in a menu is called a menu item. A menu item can:

  • Perform an action when it is clicked. This can be an action from the same set of actions as the command button or it can be an action written in C/AL. Menu items have OnPush triggers like command buttons.

  • Contain a submenu that is opened when the line is clicked.

  • Be a separator, which is a line used for grouping together items in a menu.

See Also

Tasks

How to: Add Menu Buttons to a Form


How to: Add Menu Buttons to a Form

How to: Add Menu Buttons to a Form

A menu is created in two steps. First, you add a menu button to your form. This is the same procedure that you use to add a command button. Then, you open the Menu Designer for the menu button and create the menu items.

To add a menu button

  1. Open the form in the Form Designer.

  2. Open the Toolbox and select the Menu Button tool.

  3. Select the menu button and open the Properties window (SHIFT+F4) for the menu button. Because a menu button does not have a relationship to data—field or variable—the Name and Caption properties are set to default values (such as Control7). Change the caption to the appropriate text. If the text contains an ampersand (&),the letter following the ampersand is used as an access key.

See Also

Tasks

How to: Add Menu Items to a Menu

Concepts

Adding Other Menu Items
Displaying Check Marks on Menu Items


How to: Add Menu Items to a Menu

How to: Add Menu Items to a Menu

After you have created and modified a menu button, you can add the menu items to the menu.

To add a menu item to a menu

  1. Select the button and click, View, and then click Menu Items to open the Menu Designer.

  2. The first field, Visible, is set to Yes by default. Leave this as is.

  3. Add the menu items by filling out the Caption field. If you do not create a shortcut key (by embedding an ampersand in the Caption text), the first letter of each caption will be used as a shortcut key. If you add menu items that start with the same letter, set the shortcuts yourself to avoid overloading.

  4. You can also define a shortcut key by entering the name of the key in the ShortCutKey field. The following table shows the different ways to enter keys.

    Key Entered As

    Function keys

    F1, F2, F3, ...

    CONTROL, ALT, SHIFT

    CTRL, ALT, SHIFT

    Other keys

    A, B, C, ... (these keys must be part of a key combination with CTRL or

    ALT).

    Key combinations

    For example: CTRL+A, SHIFT+F2

  5. A shortcut key is active as long as the focus is on the form that the menu button is a child of. Avoid accidentally overloading the key combinations so that they perform different actions when different forms have the focus. You should also try to avoid using shortcut keys that the system already uses.

  6. In the Action field, enter the action that you want the menu item to initiate. You can use the drop-down list to select the action from a list. Alternatively, you can write C/AL code in the OnPush trigger of the menu item.If you select RunObject you can choose to run either a form, a report, or a codeunit.

  7. In the RunObject field, click the lookup button to select the object that you want to use to run the menu item. For other parameterized actions (such as, RunSystem) you must set the parameters in the Properties window of the menu item. For more information about setting parameters, see Adding Other Menu Items.

See Also

Concepts

Adding Other Menu Items
Displaying Check Marks on Menu Items


Adding Other Menu Items

Adding Other Menu Items

In addition to items that perform actions, menus can contain separators and items that open submenus.

Separators

A separator is a horizontal line in a menu that cannot be selected or perform any action. Separators help you group items on a menu. To add a separator to a menu, select the line after which you want to insert it and click the Separator button in the Menu Designer

Submenus and Menu Levels

Menu items can be nested, that is, when you click a menu item, another menu can open.

You define submenus in the Menu Designer by indenting one or more menu items. To indent a submenu, select it and click the right-arrow button. The indented item becomes a menu item on a submenu.

In the Properties window of a menu item, when the menu item is created the MenuLevel property is set to the default value of zero. As the item are indented, the MenuLevel is set to 1, 2, 3 and so on—one level for each click on the indentation button (you can cancel indentation by clicking the left-arrow button—each click cancels one level of indentation).

There are a few logical rules that you must follow when creating submenus:

  • At least one item in each menu must have MenuLevel 0 (zero).

  • Each MenuLevel can only be one level higher than the preceding level in the list.

  • If a higher MenuLevel follows a lower one (for example, 1 follows 0), the menu item with the MenuLevel 0 opens the submenu, and the item with MenuLevel 1 becomes an item on this submenu. A menu item that opens a submenu cannot have any action associated with it.

  • There can be up to 10 menu levels (numbered from 0 to 9).

  • If the MenuLevel reverts to lower numbers (with a lesser indentation), the menu items become items in a previous menu at the level indicated by the MenuLevel.

  • Separators cannot open submenus. Separators can only separate items that are on the same level. This means that you cannot put a separator as the first, last, or only item on a menu or submenu.

See Also

Tasks

How to: Add Menu Items to a Menu

Concepts

Displaying Check Marks on Menu Items


Displaying Check Marks on Menu Items

Displaying Check Marks on Menu Items

When menu items act as a toggle key, the on or off state is indicated by the presence or absence of a check mark next to the menu item.

The SourceExpr Property

The SourceExpr property of a menu item controls whether a check mark is displayed.

Initially, the SourceExpr property is undefined. You can define it with a valid C/AL expression that evaluates to a Boolean. The check mark appears when the value is TRUE.

This feature is used in C/SIDE. For example, on the Format menu, the Snap to Grid menu item can either be on or off. When it is on, the check mark is displayed.

See Also

Tasks

How to: Add Menu Items to a Menu

Concepts

Adding Other Menu Items


Programming Guidelines for Functions in Forms

Programming Guidelines for Functions in Forms

When you write a function for a form, you may need user input for the function, such as a filter or sorting key. In this case, we recommend that you use the RunObject property of the menu item and then set a record as a parameter by reference on the codeunit instead of writing C/AL code in the OnPush trigger of the command button or menu item. The benefit of this approach is that you avoid having functionality code on the form.

Example

An example of a function that uses user input is form 251, General Journal Batches, in the CRONUS International Ltd. demo database. On this form, a user can set a filter on the name of the batch before running the Post function so that only the batches in the filter are posted. The Post function on the form is designed such that in Menu Designer for the Post menu item, the Action field is set to RunObject and the RunObject field is set to Codeunit Gen. Jnl.-B Post. This codeunit has a record of the Gen. Journal Batch table as a parameter of its OnRun function. The parameter is passed by reference. Because the parameter is passed by reference, any filters that the user set on form 251 are respected in the OnRun function of the codeunit.

Additional Filter and Sort Options

If you want to provide the user with more filtering and sorting possibilities or other option settings before starting a function, then use one of the following:

  • A report object with the ProcessingOnly property set to Yes

  • CONFIRM Function (Dialog)

  • STRMENU Function (Dialog)

See Also

Concepts

Designing Menu Buttons


Defining Form and Control Triggers

Defining Form and Control Triggers

Although the system interprets and acts upon many events in a predefined way, certain actions, such as opening a form or clicking a command button, execute a user-defined C/AL function. The event triggers the function.

Using Form and Control Triggers

You typically use triggers for advanced validation, or perhaps to format text boxes according to the value of a field or control. In short, you use triggers when the default behavior does not suit your needs.

See Also

Tasks

How to: Define and Modify Form and Control Triggers

Concepts

Form Triggers
Form Control Triggers


How to: Define and Modify Form and Control Triggers

How to: Define and Modify Form and Control Triggers

You can define a function that is triggered by a form or control event or modify an existing function.

To define or modify a form or control trigger

  1. Open the form in the Form Designer.

  2. Select the form or the control (or menu item) and click View and then click C/AL Code (F9) to open the C/AL Editor.

  3. In the editor, you have access to the triggers that apply to the object that you selected. Enter C/AL code in the triggers that you want to use, or modify the existing triggers.

  4. Click Tools and then click Compile (F11) to test and compile the form. This will include the code that you added or modified.

See Also

Concepts

Form Triggers
Form Control Triggers


Form Types and Characteristics

Form Types and Characteristics

This section describes the types of windows that are in Microsoft Dynamics NAV. It also describes the different types of form that you can create in your applications, including characteristics and examples of these forms.

With C/SIDE you can create many kinds of form that look and operate in many different ways, however Microsoft Dynamics NAV only uses a few of these forms. This gives the application a consistent look and feel.

We strongly recommend that you follow this policy for all the modifications that you make to Microsoft Dynamics NAV and for any application that interfaces with it. All the following descriptions assume that you follow the Dynamics NAV standards.

Basic Windows

There are five basic kinds of windows:

  • Dialogs

  • Request panels

  • Unbound forms

  • One-record forms

  • Multi-record forms

Dialogs

Dialogs are simple windows that display information and prompt you for a response. You can respond by pressing a button, such as OK, Cancel, Yes, or No.

These are generated by C/AL functions such as ERROR, MESSAGE, TESTFIELD, and CONFIRM, or are created by the programmer using a variable of the Dialog data type. Dialogs are not associated with forms.

Request Panels

Request panels are windows found only within reports and are not associated with forms.

Unbound Forms

Unbound forms are forms that are not associated with a table. Like Request Panels they are used when you must answer a few questions before the system can continue processing.

One-Record Forms

One-record forms are associated with a table. They let you see and edit only one record from one table at a time. A card form is a typical example of a one-record form.

Multi-Record Forms

Multi-record forms are associated with a table. They let you see multiple records from one table at a time and possibly edit them. Examples of these include Tabular Forms, TrendScape Forms, and Matrix Forms.

The forms that are associated with tables (TrendScape Forms and Matrix Forms) are the building blocks of Microsoft Dynamics NAV.

See Also

Concepts

Types of Forms and Examples
Standard Navigation


Types of Forms and Examples

Types of Forms and Examples

There are several types of standard form in Microsoft Dynamics NAV.

Standard Forms

The following table lists the most common types of form and contains some examples of each type. A more detailed description of each type appears in the following sections.

Type | Single Record/Multi-Record | Examples
Card Form | Single Record | Customer Card Vendor Card Item Card
Statistics Form | Single Record | Customer Statistics Vendor Statistics Employee Statistics
Tabular Form Currencies | Multi-Record | Payment Terms
List Form | Multi-Record | Customer List Item List Item Ledger Entries
Worksheet Form | Multi-Record | General Journal Cash Receipts Journal Item Transfer Journal
Header Form, Line Form | Single Record and Multi-Record | Sales Invoice Posted Purchase Credit Memo Finance Charge Memo
Setup Form | Single Record | General Ledger Setup Company Information Sales & Receivables Setup

Card Forms

Card Form Characteristics

A card form lets you view and edit one record in a table at a time. A card form is used when there are too many fields and you want to view them all conveniently on only one line. Card forms always have tabs (like index tabs), which you can select to view different groups of fields.

Even if there are only a few fields, there is at least one General tab. The General tab is always first.

The table's primary key field is always the first field in the General tab. Tables that use card forms only have one field in the Primary Key.

Naming Card Forms

Card forms are named after the table with which they are associated, followed by the word "Card". For example, the card form associated with the Customer table is called the Customer Card. Card forms also have at least one menu button at the bottom of the frame. This button has the same name as the table that the card is based on and gives you access to related information.

Statistics Forms

Statistics Form Characteristics

A statistics form is a one-record form that enables you to view but not edit information. It usually contains FlowFields, which allow you to drill down to get to more information. Usually, a statistics form also contains calculated or derived information contained in variables, which cannot be drilled down.

Statistics forms can also contain tabs that help organize the information.

The table's primary key is only displayed in the form's title bar.

Naming Statistics Forms

Statistics forms are named after the table with which they are associated, followed by the word "Statistics". For example, the statistics form associated with the Customer table is called Customer Statistics.

Entry statistics forms are a special version of the statistics form. They are named after the table they are associated with, followed by the words "Entry Statistics". For example, the entry statistics form associated with the Customer table is called Customer Entry Statistics.

Tabular Forms

Tabular Form Characteristics

A tabular form is a multi-record form that enables you to view multiple records from a table and edit them. Each record is displayed as a single row in the tabular form and each field is displayed as a column, creating a table within the form itself.

The primary key of the associated table is displayed in the leftmost column. If there are multiple fields in the primary key, they are displayed in order of importance in the columns, starting from the left.

Naming Tabular Forms

Tabular forms are named after the table with which they are associated—only in plural. For example, the tabular form associated with the Country/Region table is called Countries/Regions.

In the case of associated tables that have multiple fields in the primary key, the name can be different. For example, the tabular form associated with the General Posting Setup table is called General Posting Setup.

List Forms

List Form Characteristics

A list form is a multi-record form that enables you to view multiple records from a table at one time, but does not allow you to edit them. It has the same rows-and-columns look as the tabular form.

The primary key fields of the associated table are displayed in the left column.

Naming List Forms

A naming list form is named after the table with which they are associated, followed by the word "List". For example, the list form associated with the Customer table is called Customer List.

The "Specialized" Ledger Form

A more specialized version of the list form is the Ledger Form. These are used only for Ledger Entry tables. They differ from ordinary list forms, in that although you cannot insert or delete records, you can edit a few of the fields. Also, the primary key is always an integer named "Entry No." and is displayed in the rightmost column rather than the leftmost column.

The ledger form is given the plural of the name of the associated table. For example, the ledger form associated with the Customer Ledger Entry table is called Customer Ledger Entries.

Worksheet Forms

Worksheet Form Characteristics

A worksheet form is a specialized version of the tabular form. It is a multi-record form that enables you to view multiple records from a table and edit them. The difference is that when you insert a new record, the record does not jump to another position within the form, but instead stays in the same order as you inserted it.

This is done by using the AutoSplitKey property of the form, combined with an integer, as the last field in the table's primary key.

The primary key fields of the associated table are not displayed on the worksheet form.

Naming Worksheet Forms

Worksheet forms are named to reflect the purpose of the associated table. One example is a Journal table. In this case, the name of the worksheet form will end with the word "Journal".

Header/Line Forms

Header/Line Form Characteristics

Many forms have the characteristics of both a card form and a tabular form, for example the Sales Invoice form.

The fields that are common to the entire invoice are located on a card-like form with tabs, showing one invoice at a time. However, the invoice lines display in a table-like section of the form, where multiple invoice lines (from the same invoice) can be viewed at the same time and edited. These are called "Header/Line" forms.

Header/Line forms are two separate forms that are associated with two different tables. The main form is a card form that is associated with one table. The main form also contains a subform control that displays a worksheet form that is associated with a different table, a table that is "subsidiary" to the first table. The subform control manages the link between the two forms.

Naming Header/Line Forms

In many cases, a Header/Line form represents a document.

In the previous example, the Sales Invoice form is the name of the document that it represents. In other cases, the name of the form will be whatever the name of the main form would have been without the subform.

For more information about these types of situations, see Designing Tables

Setup Forms

Setup Form Characteristics

A setup form is a one-record form that enables you to view and edit the only record in a setup table. You are not allowed to insert or delete this record from this form. Since there are many fields, these forms use tabs to organize the information.

Because there is only one record, the primary key is not displayed on this form.

Naming Setup Forms

Setup forms are named after the table with which they are associated. For example, the setup form associated with the General Ledger Setup table is called General Ledger Setup.

Menu Forms

Menu Form Characteristics

A menu form is a non-bound form (not related to any table) that gives you access to many of the other forms that are related to a functional area.

The form usually consists of command buttons or menu buttons. The buttons properties change so that they look basically like labels with small squares or triangles in front of the caption. The buttons still behave like normal buttons. The only difference is their appearance.

Naming Menu Forms

Menu forms are named after the functional area with which they are associated, followed by the word "Menu". For example, the menu form associated with the

General Ledger functional area is called General Ledger Menu.

Other Multi-Record Forms

There are other forms that let you view or edit multiple records at the same time. These include TrendScape forms and Matrix forms. These forms give you greater functionality, but do not impact on the main system architecture.

An example of a TrendScape form is the Contract Trendscape window.

An example of a Matrix form is the Budget window.

See Also

Concepts

Standard Navigation


Standard Navigation

Standard Navigation

This topic describes how you navigate between forms. This is the standard type of navigation that must be supported to ensure consistency throughout the application.

Card and List Forms

Most master tables have both a card and a list form associated with them. Because both of these forms access the same table, there are many standards that determine what each form must do. The following list shows the standards that must be adhered to.

  • On the card form, you must be able to view and edit one record at a time.

  • On the list form, you must be able to view but not edit all the records. Making this form non-editable allows you to begin a search by typing in a particular column.

  • On the card form, you must be able to open the list form in the following ways:

    • By pressing F5.

    • By clicking the List menu item on the menu button with the same name as the table.

    • By clicking the List or lookup button on the toolbar.

  • In the list form, you must be able to select a new record and click OK to exit the list form and revert to the original card form. The card form must now display the record that you selected in the list form.

  • In the list form, you must be able to select a record and open a new card form by pressing SHIFT+F5 or by clicking the Card menu item on the menu button with the same name as the table. The new card form must display the record that you selected on the list form.

Master Statistics Forms

As mentioned earlier, most master tables have a card and a list form associated with them. Many master tables also have a statistics form. You should be able to open the statistics form from either the card form or the list form in exactly the same way.

The standard way to navigate to the statistics form is to click F9 or the Statistics menu item (on the menu button with the same name as the table).

Master and Ledger Forms

Usually every master table has one ledger table linked to it. From the master forms (card, list, and statistics), you must be able to open the ledger form. You must be able to open it in three different ways:

  • By clicking the drill-down button on a FlowField

  • By clicking CTRL+F5

  • By clicking the Ledger Entries menu item (on the menu button with the same name as the table)

If a drill-down button is used, only the records that are used to create the calculated value are displayed (this is a function of the built-in drill-down functionality). If the shortcut key or the menu item is used, all the ledger entries for this particular master record are shown. This requires a RunFormLink on the menu item that links the two tables. You must also keep the two forms synchronized when the master form is updated. To achieve this, you must change the RunFormLinkType property to OnUpdate.

Note For performance reasons, you should always set the RunFormView property if the RunFormLink property is also set. In fact, the sort order chosen in the RunFormView property must contain the fields listed in the RunFormLink property or else performance is decreased.

Journal Forms

Every journal form has similar buttons at the bottom of the form. These buttons allow you to navigate to another form or perform a task.

The usual buttons on a journal form include: Line, Functions, Posting, Account, and a menu button named after the master table for the functional area. This menu button must contain menu items which navigate directly to the card form for the master table or to the ledger form for the ledger entries. In both cases, the form that is opened should be linked to the master table record that the journal line is associated with.

The "Posting" menu button should contain the following menu items related to posting the journal lines: Post, Post and Print, and Test Report.

See Also

Concepts

Types of Forms and Examples


Designing and Maintaining Reports

Designing and Maintaining Reports

The following sections provide an overview of the documentation available for reporting in Microsoft Dynamics NAV 2009.

Working with Reports for the RoleTailored Client

Reports that are designed for the RoleTailored client are designed using Visual Studio to define the layout of the report. These reports can be run using the RoleTailored client to display them. For more specific design-related help in Visual Studio, see Report Designer.

To | See
Learn about designing reports for the RoleTailored client. | Designing Reports for the RoleTailored Client
Read about how to add a report to the Action Pane in the RoleTailored client. | How to: Make a Report Available in the RoleTailored Client
Learn how to quickly run a specific report that you are working on. | How to: Use a Shortcut to Run a Report
Step through creating a dynamic link from a report used to drill down into data. | Walkthrough: Creating a Link from a Report to a Page
Design a report that contains dynamic data. | Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle
Design a customer list report using Visual Studio. | Walkthrough: Designing a Customer List Report
Design a customer sales order report using Visual Studio. | Walkthrough: Designing a Customer Sales Order Report

Working with Report Redesign

If you want to redesign your existing reports to take advantage of the features in Visual Studio Report Designer, see this section to get started on working with report redesign.

To | See
Get an overview of redesigning reports with Visual Studio Report Designer. | Understanding Report Redesign
Understand the steps involved in redesigning reports. | Manual Updates to Redesigned RDLC Report Layouts
Learn how to redesign an existing report in Microsoft Dynamics NAV, the Customer List report. | Walkthrough: Redesigning a Customer List Report
Learn what properties, functions, and triggers are not supported on client report definition (RDLC) report layouts | Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client

Working with Reports for the Classic Client

If you do not want to redesign reports so they can be viewed from the RoleTailored client, it is possible to use the Classic client instead to view the reports while running the RoleTailored client.

To | See
Learn about designing reports for the Classic client. | Designing Reports for the Classic Client
Get an introduction to the basics of reports. | Report Fundamentals
See walkthroughs demonstrating the steps for creating different types of reports for the Classic client. | Classic Report Walkthroughs

See Also

Concepts

Introducing Reporting
Creating and Maintaining Forms
Creating and Maintaining Pages


Introducing Reporting

Introducing Reporting

Reporting in Microsoft Dynamics NAV 2009 is closely integrated with Visual Studio Report Designer.

RDLC Report Layouts

You can create a client report definition (RDLC) layout for Microsoft Dynamics NAV reports so they can be viewed from the RoleTailored client. This is done by using Visual Studio Report Designer. For more information, see Redesigning Classic Reports with Visual Studio Report Designer.

Viewing Classic Client Reports from the RoleTailored Client

If you do not want to create RDLC layouts for reports so that they can be viewed from the RoleTailored client, then you can use the Classic client to view the reports while running the RoleTailored client. Reports that do not have an RDLC report layout are displayed with the Classic client report viewer. If a report has its layout defined in an .rdlc file, then the report is displayed in the RoleTailored client.

Note Note

To enable viewing Classic client reports from the RoleTailored client, you must enable TCP/IP on the computer running SQL Server. To do this, start SQL Server Configuration Manager, expand the SQL Server 2005 Network Configuration node, and then click Protocols for MSSQLSERVER. If TCP/IP is not enabled, right-click TCP/IP, and then click Enable.

See Also

Concepts

Designing Reports for the RoleTailored Client
Designing Reports for the Classic Client


Designing Reports for the RoleTailored Client

Designing Reports for the RoleTailored Client

In Microsoft Dynamics NAV 2009, reports are used to extract data from the database, filter and sum the data, and then display it in a visually attractive way that gives you an overview of the data. Reports that are designed for the RoleTailored client serve the same purpose. However, the process for designing reports for the RoleTailored client is different than the process for designing reports for the Classic client, and it offers more options for creating reports that provide dynamic data.

Designing Reports

The design process is divided into distinct phases that reflect the different aspects of creating a report.

  • Defining the data model.

  • Defining the grouping and totaling.

  • Defining the visual layout.

When you define the data model, you determine the tables and fields on which to base the report. You define the data model with the Classic client Report Designer.

You define how the data that is displayed in the report should be grouped and define any totaling that should be performed in the Visual Studio Report Designer. If you need to perform complex totaling, then you must also write additional code.

You also define the visual layout of the report, such as aligning controls and inserting images, in the Visual Studio Report Designer.

Note Note

In the Visual Studio Report Designer, if you click Report, and then click Report Properties, in the Report Properties window there is an Autorefresh check box. Typically, setting this check box specifies that when you run the report, the page will refresh at periodic intervals. However, in Microsoft Dynamics NAV 2009, Autorefresh is not supported. If you enable it, then when the page refreshes it will display an empty preview page.

Loading the Report Design

When you create a report in Microsoft Dynamics NAV and later design it in the Visual Studio Report Designer, a client report definition (RDLC) layout of the report is created when you save the report. When you have designed the layout in Visual Studio, the .rdlc file for the specific report changes and you are asked to load the changes. You must click Yes to save the changes in the database.

Layout in Reports for the RoleTailored Client

With the Visual Studio Report Designer, you can create reports that provide dynamic data. Microsoft Dynamics NAV reports can include images, graphics, toggles on data columns, interactive sorting, and links to other data. For more information, see Defining a Report Layout (Visual Studio Report Designer).

You can create links in a report so that it is not just a static, printed list but instead is a dynamic list that can be used to drill-down into system data. For more information, see Walkthrough: Creating a Link from a Report to a Page and Walkthrough: Creating a Link from a Report to a Report.

You can also include images and graphs in a report to serve as visual aids when representing complex data. With the introduction of visibility toggle and interactive sorting, users can hide data columns that do not always contain data to get a better overview of data. Interactive sorting allows users to interactively change the sort order for data columns. For more information, see Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle.

See Also

Tasks

Walkthrough: Designing a Customer List Report
Walkthrough: Designing a Customer Sales Order Report
How to: Make a Report Available in the RoleTailored Client
Walkthrough: Creating a Link from a Report to a Page
Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle


How to: Make a Report Available in the RoleTailored Client

How to: Make a Report Available in the RoleTailored Client

After you have created and designed a report using Visual Studio, you must also add the report to the interface of the RoleTailored client. The following procedure explains how to make a report available in the RoleTailored client by adding the report to the promoted actions pane in the Customer List page.

To make a report available in the RoleTailored client

  1. In the Microsoft Dynamics NAV Classic client, open Object Designer, and then click Page.

  2. Select the page to display the report, for example, Page 22, Customer List.

  3. Click Design to open the page in Page Designer.

  4. Select an empty line in the designer. Click View, and then Actions to open Action Designer.

  5. Scroll down to the ActionContainer that has Reports as its subtype.

  6. Add an action to the list; in the Caption field enter a name for the action, and in the Type field, select Action.

  7. Click View, and then Properties to open the Properties window for the new action.

  8. In the Value field of the RunObject property, click the drop-down arrow and select the new report in the Object List window.

  9. Set the Push Action property to RunObject, set the Promoted property to Yes, and set the PromotedCategory property to Report.

  10. Compile and save the page.

  11. Open the RoleTailored client and then open the Customer List page.

    The report is added to the list of promoted actions. Click the action to run the report.

See Also

Tasks

Walkthrough: Designing a Customer List Report
Walkthrough: Designing a Customer Sales Order Report

Concepts

Designing Reports for the RoleTailored Client
Designing Reports for the Classic Client


How to: Use a Shortcut to Run a Report

How to: Use a Shortcut to Run a Report

You can run reports directly at the command prompt if you know the ID of the report. This can be useful if you need to run a specific report for testing or you know the ID of a report that you run often.

In addition, you can filter the data in the report by adding a filter string to the command. The filter string has the following format:

CopyCode image Copy Code
&filter=<table>.<field>:<value>

To specify the table, you use the DataItemVarName of the data item. For more information, see DataItemVarName Property.

To specify the field, use the field name. If the field name contains special characters, then you must enclose it in quotation marks by using the URI escape sequence %22.

The colon operator separates the two parts of the filter string.

To specify the value, you can either use a single value or a comparison operator and a value. The following are the valid comparison operators:

  • > (greater than)

  • >= (greater than or equal to)

  • < (less than)

  • <= (less than or equal to)

  • <> (not equal to)

The wildcard character * is permitted in the value.

You can specify multiple filter strings by concatenating them. For example, the following command filters on cities that begin with M and names that begin with A.

CopyCode image Copy Code
DynamicsNAV:////runreport?report=104&filter=Customer.City:M*&filter=Customer.Name:A*

To use a shortcut to run a report

  1. In Windows, on the taskbar, click Start and then click Run.

  2. In the Run dialog box, enter the following command: dynamicsnav:////runreport?report=<ReportID>[&filter=<table>.<field>:<value>]

  3. Replace <ReportID> with the report ID that you want to run. If you want to filter the data, then replace <table>, <field>, and <value> with the appropriate values.

  4. Click OK to run the report.

See Also

Concepts

Designing Reports for the RoleTailored Client
Designing Reports for the Classic Client


How to: Add Totals in Visual Studio

How to: Add Totals in Visual Studio

Totals are an important element of creating useful reports. By totaling data, your report can help the user analyze data that is not otherwise readily available. For example, totals provide a useful overview of the total sales for a given month. Reports can be created with Microsoft Dynamics NAV 2009 and later designed using Visual Studio. This topic describes how to add totals to a report in Visual Studio.

To add totals in Visual Studio

  1. In Visual Studio, right-click the total field on the report and select Expression.

  2. In the Expression window enter the following expression: =SUM(Fields!<tablefield>.Value)For example: =SUM(Fields!Sales_Line_Amount.Value)

  3. Save the report in Visual Studio.

  4. Compile and save the report in Microsoft Dynamics NAV 2009. A message informs you that the .rdlc file for this report has changed and asks if you want to load the changes. Click Yes to save the changes in the database.

See Also

Tasks

Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle
Walkthrough: Creating a Link from a Report to a Page
How to: Make a Report Available in the RoleTailored Client

Concepts

Requirements for Developing Reports for the RoleTailored Client


Printing Reports

Printing Reports

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009. Additionally, the content in this topic only applies to an installation that includes the hotfix that is described in Knowledge Base article 976646: A report is always printed in portrait orientation even though you set the Orientation property of the report to Landscape in Microsoft Dynamics NAV 2009 with Service Pack 1 installed.

You can specify page settings and page orientation for a printed report from the following UI locations:

  • The Report Properties dialog box on the client report definition (RDLC) report layout in Visual Studio

  • The Properties dialog box for the printer

  • The Print dialog box that is displayed immediately before you print

  • The Page Setup dialog box from the Print Preview page in the RoleTailored client

The page settings that are used for the printed report depend on the mode in which you print the report.

You can use the following modes to print a report from the RoleTailored client:

  • Run a report that has the UseReqForm Property set to No, and therefore, does not display a request page

  • Print a report from the request page without previewing the report

  • Print a report from the Print Preview page

Note Note

The printer that you use determines how to handle the case in which the actual paper size in the printer is different from the page size that is specified.

Specifying Page Settings and Orientation

The following table describes how you access each of the dialog boxes in which you can specify page settings and orientation.

Print mode | To access the Report Properties dialog box… | To access the Properties dialog box for the printer… | To access the Print dialog box… | To access the Page Setup dialog box…
Run a report that does not have a request page… | When you design the report layout in Visual Studio, on the Report menu, click Report Properties. | In Control Panel, double-click Printers. Right-click the selected printer and then click Properties. | Cannot access | Cannot access
Print a report from the request page without previewing… | When you design the report layout in Visual Studio, on the Report menu, click Report Properties. | In Control Panel, double-click Printers. Right-click the selected printer and then click Properties. | On the request page, click Print. | Cannot access
View a preview of a report… | When you design the report layout in Visual Studio, on the Report menu, click Report Properties. | In Control Panel, double-click Printers. Right-click the selected printer and then click Properties. | In the Print Preview window, click the Print icon. | In the Print Preview window, click the Page Setup icon.

How Printed Report Settings Are Determined

Because there are several locations in the UI where you can specify page settings and orientation, you should know how the settings are determined for a printed report. How the settings are determined depends on the mode that you use to print the report.

Printing a Report Without a Request Page

The following table describes the page settings and orientation that are used if you print a report that does not have a request page.

If… | Then the printed report paper size and margins are determined by… | Then the printed report orientation is determined by…
The settings in the Report Properties dialog box on the layout of the report specify a standard paper size | The settings in the Report Properties dialog box on the RDLC layout | The settings in the Properties dialog box for the printer
The settings in the Report Properties dialog box on the layout of the report specify a custom paper size | The settings in the Properties dialog box for the printer | The settings in the Properties dialog box for the printer

Printing a Report From the Request Page

The following table describes the page settings and orientation that are used if you print a report from the request page without previewing the report.

If… | Then the printed report paper size and margins are determined by… | Then the printed report orientation is determined by…
The settings in the Report Properties dialog box on the layout of the report specify a standard paper size | The settings in the Report Properties dialog box on the RDLC layout, but is overridden if you change the settings in the Print dialog box | The settings in the Report Properties dialog box on the RDLC layout, but is overridden if you change the settings in the Print dialog box
The settings in the Report Properties dialog box on the layout of the report specify a custom paper size | The settings in the Properties dialog box for the printer, but is overridden if you change the settings in the Print dialog box | The settings in the Report Properties dialog box on the RDLC layout, but is overridden if you change the settings in the Print dialog box
Note Note

The values in the Print dialog box are initially set to the values from the Report Properties dialog box on the RDLC report layout.

Printing a Report From the Preview Page

The following table describes the page settings and orientation that are used if you print a report from the Print Preview page.

If… | Then the printed report paper size and margins are determined by… | Then the printed report orientation is determined by…
The settings in the Report Properties dialog box on the layout of the report specify a standard paper size | The settings in the Report Properties dialog box on the RDLC layout, but is overridden if you change the settings in the Page Setup dialog box | The paper size settings in the Report Properties dialog box on the RDLC layout, but is overridden if you change the settings in the Page Setup dialog box
The settings in the Report Properties dialog box on the layout of the report specify a custom paper size | The settings in the Report Properties dialog box on the RDLC layout, but is overridden if you change the settings in the Page Setup dialog box | The paper size settings in the Report Properties dialog box on the RDLC layout, but is overridden if you change the settings in the Page Setup dialog box
Note Note

The values in the Page Setup dialog box are initially set to the values from the Report Properties dialog box on the RDLC report layout.


RoleTailored Client Report Walkthroughs

RoleTailored Client Report Walkthroughs

The following topics describe end-to-end processes that you can follow to design and modify reports for the RoleTailored client.

In This Section

Documentation | Description
Walkthrough: Creating a Link from a Report to a Page | Describes how to modify the Customer - Top 10 List report to include a link to the customer card.
Walkthrough: Creating a Link from a Report to a Report | Describes how to modify the Customer - Top 10 List report to include a link to the Customer - Detail Trial Bal. report.
Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle | Describes how to create a report that displays images, allows interactive sorting, and visibility toggle.
Walkthrough: Designing a Customer List Report | This walkthrough describes how to create a simple report based on one table with Microsoft Dynamics NAV and design this report using Visual Studio Report Designer.
Walkthrough: Designing a Customer Sales Order Report | Describes how to create a report based on two tables with Microsoft Dynamics NAV and design this report in Visual Studio.
Walkthrough: Modifying the Customer - Top 10 List Report | Describes how to use the capabilities in Visual Studio Report Designer to modify the initial layout suggestion for the Customer - Top 10 List report into a more user-friendly report with formatted text, color, and charts.

See Also

Concepts

Designing and Maintaining Reports


Walkthrough: Creating a Link from a Report to a Page

Walkthrough: Creating a Link from a Report to a Page

You can create reports that provide dynamic data with Visual Studio Report Designer and Microsoft Dynamics NAV 2009. Your reports can include images, graphics, toggles on data columns, interactive sorting, and links to other data in the system. This walkthrough illustrates how to set up a report to include a link to the customer card page. When the report is run in preview mode, you can look up any existing customer directly from the report. By including this functionality, you now have a report that is a dynamic list that you can use to drill down into data instead of a report that is a static, printed list.

Expand image About This Walkthrough

The walkthrough provides an overview of how to modify the Customer - Top 10 List report to include a link to the customer card. This walkthrough illustrates the following tasks:

  • Enabling hyperlinks on a report.

  • Adding a variable and code to the Customer - Top 10 List report definition.

  • Adding a text box to the Customer - Top 10 List report layout.

  • Adding a link to the customer name on the report using Visual Studio.

  • Running the modified report.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Visual Studio. For more information about versions of Visual Studio that you can use, see Requirements for Developing Reports for the RoleTailored Client.

Expand image Enabling Hyperlinks on a Report

Before you can add a link from a report to a page, you must enable hyperlinks on the report. For more information, see EnableHyperlinks Property.

To enable hyperlinks on a report

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select report 111, the Customer - Top 10 List report, and then click Design.

  3. In Report Designer, select an empty line.

  4. On the View menu, click Properties.

  5. In the Properties window, in the EnableHyperlinks field, select Yes.

  6. Save and compile the report.

Expand image Adding a Variable and Code to the Report

In the following procedure, you will add a variable that holds a reference to the current customer record in the report.

To add a variable and code to the report

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, and then locate the Customer - Top 10 List report by typing object ID 111.

  3. Select the Customer - Top 10 List report, and then click the Design button.

  4. In Report Designer, select the Customer data item, and then on the View menu, click C/AL Globals.

  5. On the Variables tab, add a new entry. In the Name field, enter CustomerRecRef, and in the DataType field, select RecordRef.

  6. Close the C/AL Globals window.

  7. In Report Designer with the Customer data item still selected, on the View menu, click C/AL Code.

  8. In the C/AL Editor window, on the OnPreDataItem trigger, add the following line of code:

    CopyCode image Copy Code
    CustomerRecRef.OPEN(18);

  9. In Report Designer, change focus to the Integer data item.

  10. In the C/AL Editor window, on the OnAfterGetRecord trigger, add the following line of code:

    CopyCode image Copy Code
    CustomerRecRef.SETPOSITION(Customer.GETPOSITION);

  11. Close the C/AL Editor window and save the report.

Expand image Adding a Text Box to the Report

After creating the CustomerRecRef variable, you must create a new text box that is used to get the value of the current customer that is represented in the dataset in Visual Studio once the layout is opened there. The text box is not visible on the report when it is run but is only used for layout purposes. For more information, see How to: Resolve Formatting Issues Caused by Hidden Fields. The following steps illustrate how to add the text box to the report.

To add a text box to the report

  1. With the Customer - Top 10 List report open in Report Designer, on the View menu, click Sections.

  2. In Section Designer, locate the BarText text box, and then resize it to make room for a new small text box.

  3. On the View menu, click Toolbox.

  4. Click Textbox and then click on the report design to place it next to the BarText text box.

  5. Right-click the new Textbox, and then click Properties.

  6. In the Properties window, on the SourceExpr property, enter the following expression:

    FORMAT(CustomerRecRef.RECORDID,0,10)

  7. Close the Properties window.

    Note Note

    The usage of value 10 in this expression is a RoleTailored client feature only that will format RECORDID into a text representation that is compatible with the URL handler of reports and pages.

  8. Save and compile the report.

Expand image Adding a Link to Customer Name in Visual Studio

Once you have created the variable and text box with Report Designer, you can open and modify the layout of the report in Visual Studio. The following steps will add a link to the customer name on the report that opens the customer card for the selected customer. The text box that you created in Microsoft Dynamics NAV is part of the dataset in Visual Studio under Data Sources, and its value is referenced in the link you are adding.

To add a link to customer name in Visual Studio

  1. In the Classic client, with the Customer - Top 10 List report open in Report Designer, on the View menu, click Layout.

  2. In Visual Studio, in the Body section of the report, locate the Customer_Name text box. The value of the textbox is =Fields!Customer_Name.Value.

  3. Right-click the textbox, and then click Properties.

  4. In the Properties window, click the Navigation tab.

  5. Select the Jump to URL check box and enter the following line in the field below: ="dynamicsnav:////runpage?page=21&mode=edit&bookmark="+Fields!FORMAT_CustomerRecRef_RECORDID_0_10_.Value

    Note Note

    This line opens the page in edit mode.

  6. Click OK to close the window.

  7. Save the report in Visual Studio and return to the Classic client.

Expand image Running the Modified Report

In the Classic client, you must now save the modified report and compile it before it can be run.

To run the modified report

  1. In the Classic client, save the Customer - Top 10 List report. A message informs you that the .rdlc file for this report has changed and asks if you want to load the changes. Click Yes to save the changes in the database.

  2. On the Tools menu, click Compile to compile the report.

  3. On the Windows taskbar, click Start, and then click Run.

  4. In the Run window, enter the following text: dynamicsnav:////runreport?report=111, and then click OK.

  5. Click Preview to view the report. The report lists the top 10 list of customers. If you hover on the customer name, then you will get a link to open the specific customer on a separate customer card. This makes it possible to drill down into the customer's data.

Expand image See Also

Tasks

Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle
Walkthrough: Designing a Customer List Report
Walkthrough: Designing a Customer Sales Order Report
How to: Resolve Formatting Issues Caused by Hidden Fields


Walkthrough: Creating a Link from a Report to a Report

Walkthrough: Creating a Link from a Report to a Report

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

This walkthrough illustrates how to set up a report to include a link from the Customer - Top 10 List report to the Customer - Detail Trial Bal. report. When you run the Customer - Top 10 List report in preview mode and show balance data, you can click either a value in the Balance (LCY) column or a section of the pie chart to view detailed balance information. By including this functionality, you now have a report that is dynamic and that you can use to drill down into data instead of a report that is static.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Enabling hyperlinks on a report.

  • Adding a link from the balance text box on the report to another report.

  • Formatting the balance text box to indicate that it is a link.

  • Adding a link from the pie chart to another report.

  • Running the modified report.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 SP1 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Visual Studio. For more information about versions of Visual Studio that you can use, see Requirements for Developing Reports for the RoleTailored Client.

Expand image Enabling Hyperlinks on a Report

Before you can add a link from a report to another report, you must enable hyperlinks on the report. For more information, see EnableHyperlinks Property.

To enable hyperlinks on a report

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select report 111, the Customer - Top 10 List report, and then click Design.

  3. In Report Designer, select an empty line.

  4. On the View menu, click Properties.

  5. In the Properties window, in the EnableHyperlinks field, select Yes.

  6. Save and compile the report.

Expand image Adding a Link from the Balance Text Box

In the following procedure, you add a link from the balance text box in report 111, the Customer - Top 10 List report to report 104, the Customer Detail Trial Bal. report.

To add a link from the Balance Field

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select report 111, the Customer - Top 10 List report, and then click Design.

  3. On the View menu, click Layout.

  4. In Visual Studio, in the Body section of the report, locate the Customer__Balance__LCY__ text box. The value of the textbox is =Fields!Customer__Balance__LCY__.Value.

  5. Right-click the text box, and then click Properties.

  6. In the Properties window, click the Navigation tab.

  7. Select the Jump to URL check box and enter the following line in the field below the Jump to URL check box:

    CopyCode image Copy Code
    ="dynamicsnav:////runreport?report=104&filter=Customer.%22No.%22:"+Fields!Customer__No__.Value

    For more information about creating filters in a URL to run a report, see How to: Use a Shortcut to Run a Report.

  8. Click OK to close the window.

  9. Save the report in Visual Studio.

Expand image Formatting the Balance Text Box

After adding the link from the balance text box to report 104, you may want to change the format of the balance text box to indicate that the data in the text box is also a link. The following steps illustrate how to format the text box.

To format the balance text box

  1. In Visual Studio, in the Body section of the report, select the Customer__Balance__LCY__ text box.

  2. On the View menu, click Properties Window.

  3. In the Properties window, in the Color field, select Blue. In the Text Decoration field, select Underline.

  4. Save the report in Visual Studio.

Expand image Adding a Link from a Pie Chart

The following steps add a link from the data in the pie chart to report 111.

To add a link from a pie chart

  1. In Visual Studio, right-click the pie chart, and then click Properties.

  2. In the Chart Properties window, click the Data tab.

  3. Next to the Values field, click Edit.

  4. In the Edit Chart Value window, on the Action tab, select the Jump to URL check box and enter the following line in the field below the Jump to URL check box:

    CopyCode image Copy Code
    ="dynamicsnav:////runreport?report=104 &filter=Customer.%22No.%22:"+Fields!Customer__No__.Value

    For more information about creating filters in a URL to run a report, see How to: Use a Shortcut to Run a Report.

  5. Click OK to close the Edit Chart Value window. Click OK to close the Chart Properties window.

  6. Save and close the report in Visual Studio.

Expand image Running the Modified Report

In the Classic client, you must now save the modified report and compile it before it you can run the report.

To run the modified report

  1. In the Classic client, save the Customer - Top 10 List report. In the Save window, verify that the Compiled check box is selected, and then click OK.

    A message informs you that the .rdlc file for this report has changed and asks if you want to load the changes. Click Yes to save the changes in the database.

  2. In the RoleTailored client, run the Customer - Top 10 List report. You can run the report either from the Reports menu on the Customers list or you can enter the following command at the command prompt:

    dynamicsnav:////runreport?report=111

  3. In the request page for report 111, under Options, in the Show field, select Balance (LCY). In the Chart Type field, select Pie chart.

  4. Click Preview to view the report. The report lists the top 10 list of customers. If you click a value in the Balance (LCY) column or if you click a section of the pie chart, then the Customer - Detail Trial Bal. report opens for the specified customer.

Expand image See Also

Tasks

Walkthrough: Creating a Link from a Report to a Page

Other Resources

RoleTailored Client Report Walkthroughs


Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle

Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle
See Also
CollapseAll image

In Microsoft Dynamics NAV 2009, the process of creating new reports is divided into three phases:

  • Defining the data model on which the report is based.

  • Defining grouping and totaling for the report.

  • Designing the visual layout of the report.

With Microsoft Dynamics NAV, you can use Visual Studio Report Designer to design and edit the visual layout of a report.

Expand image About This Walkthrough

This walkthrough provides an overview of how to create a report that displays images, allows interactive sorting, and provides visibility toggling. This walkthrough illustrates the following tasks:

  • Defining the data model in Microsoft Dynamics NAV.

  • Designing the report layout using Visual Studio Report Designer.

  • Synchronizing the report layout with Microsoft Dynamics NAV and running the report.

  • Applying interactive sorting to the report layout using Visual Studio Report Designer.

  • Resynchronizing the report layout with Microsoft Dynamics NAV and running the report.

For more information about designing the layout of a report with Visual Studio, see Defining a Report Layout (Visual Studio Report Designer).

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Visual Studio. For more information about versions of Visual Studio that you can use, see Requirements for Developing Reports for the RoleTailored Client.

Expand image Defining the Data Model

When you create a new report, you must define where the data that the report will display should come from. You define the data model in Microsoft Dynamics NAV.

To define the data model

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, and then click New to open the New Report window.

  3. In the Table field, click the drop-down arrow, and then select the Item table with ID 27 in the Table List window.

  4. Select Create a blank report, and then click OK. The Report Designer window opens.

  5. In the DataItem field, select the Item table from the Table list, and then click OK.

  6. On the View menu, click Sections to open Section Designer.

  7. On the View menu, click Field Menu.

  8. In the Field Menu window, select the No., Description, and Picture fields. Click on the design area twice to add the fields.

  9. Close the windows, and then click Yes to save the report.

  10. In the ID field, enter 50000, and name the report ItemReport.

  11. Click OK.

Expand image Designing the Report Layout

Now that you have defined the data model for the report in Microsoft Dynamics NAV, you can design and refine the layout in Visual Studio.

To design the report layout in Visual Studio

  1. In the Classic client, select the ItemReport that you created, and then click Design.

  2. On the View menu, click Layout. The report opens in Visual Studio. The report layout is empty.

  3. In Visual Studio, on the View menu, click Toolbox.

  4. From the Toolbox, drag a Table to the report.

  5. On the Data menu, click Show Data Sources.

  6. From Data Sources, drag the Item_No_Caption field to the first column, first row of the table in the Header section of the report layout. Then drag the Item_No field to the first column, second row of the table in the Detail section of the report layout.

  7. From Data Sources, drag the Item_DescriptionCaption field to the second column, first row of the table in the Header section. Then drag the Item_Description field to the second column, second row of the table in the Detail section.

  8. From Data Sources, drag the Item_PictureCaption field to the third column, first row of the table in the Header section.

  9. From the Toolbox, drag an Image to the third column, second row of the table in the Detail section.

  10. On the View menu, click Properties Window.

  11. In the Properties window, set the following properties.

    Note Note

    When you set the Source property, the items in the MIMEType drop-down list change. You must set the Source property to Database so that the image/bmp value is available in the MIMEType drop-down list.

    Property Setting

    Source

    Database

    MIMEType

    Image\bmp

    Value

    =Fields!Item_Picture.Value

  12. In the File menu, click Save Report.rdlc.

Expand image Synchronizing and Running the Report

Now you will load the changes that you made in Visual Studio to Microsoft Dynamics NAV to synchronize the two versions of the ItemReport.

To synchronize and run the report

  1. In the Classic client, open ItemReport in Report Designer. A message informs you that the .rdlc file for this report has changed and asks if you want to load the changes. Click Yes to save the changes in the database.

  2. On the Tools menu, click Compile to compile the ItemReport.

  3. On the Windows taskbar, click Start, and then click Run.

  4. In the Run window, enter the following text: DynamicsNAV:////runreport?report=50000, and then click OK.

  5. Click Preview to view the report.

  6. Close the report and run the report again with filter Picture set to 1. Only items that have associated pictures are printed.

  7. Close the report.

Expand image Setting Up Interactive Sorting

The report now displays a list of items with a description and a picture of the item. You can filter the report to only view items that have a picture associated with them, as shown in step 6 in the preceding section. Now you will add interactive sorting to the ItemReport. Interactive sorting will allow users to interactively change the sort order for the data columns. By using the sort control button in the column header on the report, the user can change the sort order between ascending and descending.

To set up interactive sorting

  1. In the Classic client, open the ItemReport in Report Designer.

  2. On the View menu, click Layout. The report opens in Visual Studio.

  3. Right-click the Item_No_Caption field, and then click Properties.

  4. In the Properties window, click the Interactive Sort tab.

  5. On the Interactive Sort tab, select the Add an interactive sort action to this textbox field.

  6. In the Sort expression: field, select the expression =Fields!Item_No_.Value from the list, and then click OK.

  7. Right-click the Item_DescriptionCaption header, and then click Properties.

  8. In the Properties window, click the Interactive Sort tab.

  9. On the Interactive Sort tab, select the Add an interactive sort action to this textbox field.

  10. In the Sort expression: field, select the expression =Fields!Item_Description.Value, and then click OK.

  11. Right-click the Image field, and then click Properties.

  12. In the Properties window, click the Visibility tab, and then select the Visibility can be toggled by another report item field.

  13. In the Report item: field, select Item_No_Caption, and then click OK.

  14. In the File menu, click Save Report.rdlc.

Expand image Resynchronizing and Running the Report

After you have applied the latest changes to the report in Visual Studio, you will load the changes that you made in Microsoft Dynamics NAV to synchronize the two versions of the ItemReport. After the changes have been loaded, you can run the report to see the interactive sorting functionality.

To resynchronize and run the report

  1. In the Classic client, open the ItemReport in Report Designer. A message informs you that the .rdlc file for this report has changed and asks if you want to load the changes. Click Yes to save the changes in the database.

  2. On the Tools menu, click Compile to compile the ItemReport.

  3. On the Windows taskbar, click Start, and then click Run.

  4. In the Run window, enter the following text: DynamicsNAV:////runreport?report=50000, and then click OK.

  5. Click Preview to view the report. You can use interactive sorting for the No. and Description columns. You can also collapse the list and display the No. and Description columns without pictures.

Expand image See Also

Tasks

Walkthrough: Designing a Customer List Report
Walkthrough: Designing a Customer Sales Order Report


Walkthrough: Designing a Customer List Report

Walkthrough: Designing a Customer List Report

In Microsoft Dynamics NAV 2009, the process of creating new reports is divided into three phases:

  • Defining the data model on which the report is based.

  • Defining grouping and totaling for the report.

  • Designing the visual layout of the report.

With Microsoft Dynamics NAV, you can use Visual Studio Report Designer to design and edit the visual layout of a report.

Expand image About This Walkthrough

This walkthrough provides an overview of how to create a report that is based on one table with Microsoft Dynamics NAV and design this report using Visual Studio Report Designer. This walkthrough illustrates the following tasks:

  • Create a report in Microsoft Dynamics NAV.

  • Apply sorting criteria and filters on the report in Microsoft Dynamics NAV.

  • Design the layout of the report in Visual Studio.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Visual Studio. For more information about versions of Visual Studio that you can use, see Requirements for Developing Reports for the RoleTailored Client.

Expand image Defining the Data Model

When you create a new report, you must define where the data that the report will display should come from. You define the data model in Microsoft Dynamics NAV.

To define the data model

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, and then click the New button to open the New Report window.

  3. In the Table field, click the drop-down arrow, and then select the Customer table in the Table List window.

  4. Select Create a report using a wizard, and then choose Tabular-Type Report Wizard. Click OK.

  5. In the Tabular-Type Report Wizard, select the No., Name, Address, and Phone No. fields, and then click Next.

  6. Accept the default selection for the report in the next windows.

  7. Click the Finish button, and the Report Designer window opens.

Expand image Applying Sorting Criteria and Filters

Next, you must decide what sorting criteria and filters that can be used in the report. This report will sort the customers in ascending order by customer number and have a filter for searching by customer number and country/region code.

To set the report properties

  1. In Report Designer, select the Customer data item.

  2. On the View menu, click Properties.

  3. In the Properties window, select the DataItemTableView property, and in the Value field, click the drop-down arrow to open the Table View property.

  4. Select the No. field as the key, and then set the sort order to Ascending. Click OK.

  5. In the Properties window for the Customer data item, select the ReqFilterFields property, and in the Value field, click the drop-down arrow to open the Field List window.

  6. Select the No. and Country/Region Code fields, and then click OK.

  7. On the File menu, click Save As.

  8. Give the report ID 55551 and the name CustomerList.

  9. Click OK to save and compile the report.

Expand image Designing the Report Layout

After you have saved and compiled the report in the Classic client, you must transform the layout and open it in Visual Studio. You can then use Visual Studio to edit and design this report. For this report, you will set the header to use a larger font and the company name to use the red font color.

To design the layout of the report

  1. In the Classic client, in Object Designer, locate the CustomerList report, and then click the Design button.

  2. On the Tools menu, click Create Layout Suggestion. Visual Studio opens and displays the current layout of the report.

  3. In the Page Header section of the layout, click the CustomerCaption1 text box.

  4. On the View menu, click Properties Window.

  5. In the Properties window, expand the Font property and select FontSize. Set FontSize to 12pt.

  6. In the Page Header section of the layout, click the COMPANYNAME1 text box.

  7. On the View menu, click Properties Window.

  8. Set the Color property to Red.

  9. Save the report in Visual Studio.

  10. In the Classic client, open the same report in Report Designer. A message informs you that the .rdlc file for this report has changed and asks if you want to load the changes. Click Yes to save the changes in the database.

  11. Compile the report.

  12. Click Run to run the report from the Classic client.

  13. To view the changes that you made in Visual Studio, run the report in the RoleTailored client. For more information about running a report in the RoleTailored client, see How to: Use a Shortcut to Run a Report.

Expand image Next Step

  • Now you have created a report that lists customers sorted by customer number, and you have added a few changes to the report layout using Visual Studio. The next step is to add the customer list report to a page in the RoleTailored client from where it can be run. For more information, see How to: Make a Report Available in the RoleTailored Client.

Expand image See Also

Tasks

How to: Make a Report Available in the RoleTailored Client
Walkthrough: Creating a Link from a Report to a Page
Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle
Walkthrough: Designing a Customer Sales Order Report


Walkthrough: Designing a Customer Sales Order Report

Walkthrough: Designing a Customer Sales Order Report

In this walkthrough, you will learn how to create a report that is based on two tables. The report lists customers and their orders, and it is based on the Customer and Sales Line tables. This type of report can be used to get an overview of the current customer orders. This walkthrough is based on the Walkthrough: Designing a Customer List Report topic.

Expand image About this Walkthrough

This walkthrough provides an overview of how to create a report based on two tables with Microsoft Dynamics NAV and design both the Classic layout of this report in Report Designer and the client report definition (RDLC) layout in Visual Studio. The walkthrough illustrates the following tasks:

  • Modify the dataset of an existing report in Microsoft Dynamics NAV.

  • Add fields to the Classic report layout.

  • Redesign the RDLC report layout in Visual Studio Report Designer to add fields.

  • Add grouping and totaling to the Classic report layout

  • Add grouping and totaling to the RDLC report layout in Visual Studio Report Designer.

  • Run the modified report.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Visual Studio. For more information about versions of Visual Studio that you can use, see Requirements for Developing Reports for the RoleTailored Client.

  • Completion of Walkthrough: Designing a Customer List Report.

Expand image Modifying the Dataset of an Existing Report

You will add an additional Microsoft Dynamics NAV table to the dataset of the existing customer list report.

To modify the dataset of an existing report

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, and then locate the CustomerList report with ID 55551.

  3. Click the Design button.

  4. In the Data Item field, enter the Sales Line table as the second data item.

  5. Select the Sales Line data item, and then click the right-arrow button once to indent it.

  6. On the View menu, click Properties to open the Properties window for the Sales Line data item.

  7. Set the DataItemLinkReference property to Customer. In most cases, this is the default setting. This specifies that the Sales Line data item is linked to the Customer data item.

  8. To specify the field in the Sales Line data item and the field in the Customer data item that are linked, do the following:

    1. In the Value field of the DataItemLink property, click the drop-down arrow to open the DataItem Link window.

    2. In the Field field, enter the name of the field from the Sales Line table that must correspond to a field from the Customer table. For this report, select the Sell-to Customer No. field.

    3. In the Reference Field field, enter the name of the field from the Customer table that corresponds to the field from the Sales Line table. For this report, select the No. field, and then click OK.

  9. Open the Properties window for the Customer data item, and then set the PrintOnlyIfDetail property to Yes to only print the Customer body section if there is data to print from the Sales Line table.

  10. Save and compile the report.

Expand image Adding Fields to the Classic Report Layout

After adding an extra table to the report dataset, you will add and display the fields from the new table in the Classic report layout.

To add fields to the Classic report layout

  1. With the report still open in Report Designer, on the View menu, click Sections to open Section Designer.

  2. In Report Designer, select the Sales Line data item.

  3. On the View menu, click Field Menu to open the Field Menu window, which lists the fields in the Sales Line table.

  4. In the Field Menu window, select the new fields to display on the report. For this report, select the No., Document No., Shipment Date, Description, Quantity, Unit Price, and Line Amount fields.

    Note Note

    The No. field is selected because you will use it later for grouping.

    Note Note

    To select multiple fields in the Field Menu window, hold down the CTRL key while you select the fields.

  5. Move the cursor into the Sales Line Body section of the layout. Click once to activate the window—the cursor changes into the Control Insertion cursor. Place the cursor on the left side of the section and click again. A text box with an attached label is inserted for each field that you selected.

  6. Close Section Designer, close the Field Menu window, save, and compile the report.

Expand image Designing the RDLC Report Layout in Visual Studio Report Designer

After you load the redesigned report in Visual Studio, you can define the report layout. When you open the report in Visual Studio, you will see that the new fields have not yet been added to the layout.

Note Note

If you had created a layout suggestion in Microsoft Dynamics NAV, then you would have seen these fields in the report. However, the design that you implemented in the Walkthrough: Designing a Customer List Report topic would have been lost. For more information about creating a layout suggestion, see How to: Create a Layout Suggestion.

All the fields that you added in Microsoft Dynamics NAV are available from the Data Sources pane in Visual Studio. You can drag and drop them to add them to the report.

To design the RDLC report layout in Visual Studio Report Designer

  1. With the report still open in Report Designer, on the View menu, click Layout to open the report in Visual Studio Report Designer.

  2. In Visual Studio, click the table data region of the layout.

  3. Insert two rows below. Resize the column width as necessary. Change font.

  4. In the Data Sources pane, expand DataSet and expand Result.

  5. Drag and drop each of the following fields the Data Sources pane to the first empty row of the table data region of the report layout:

    • Sales_Line__Document_No__Caption

    • Sales_Line__Shipment_Date_Caption

    • Sales_Line_DescriptionCaption

    • Sales_Line_QuantityCaption

    • Sales_Line__Unit_Price_Caption

    • Sales_Line__Line_Amount_Caption

  6. Drag and drop each of the following fields the Data Sources pane to the last empty row of the table data region, in the column that corresponds to the caption:

    • Sales_Line__Document_No__

    • Sales_Line__Shipment_Date_

    • Sales_Line_Description

    • Sales_Line_Quantity

    • Sales_Line__Unit_Price_

    • Sales_Line__Line_Amount_

  7. Save the report in Visual Studio, and then close Visual Studio.

  8. Save and compile the report in the Classic client.

  9. Open the RoleTailored client, and then run the report to see that the additional fields from the Sales Line table are added.

Expand image Adding Grouping and Totaling to the Classic Report Layout

The customer sales order report does not at this point tell us how much each customer has ordered in total. By grouping and totaling data, your reports can contain information that is not otherwise readily available.

The report is based on two tables and lists customers and customer sales lines that are related to each customer. In the Walkthrough: Designing a Customer List Report, you sorted the data by customer number. To provide statistics, you also want to group sales lines according to item number instead of printing all lines from all sales documents. Each line will then contain figures for the total quantity and the total amount for each item per customer. Also, it is useful to have a total amount per customer that shows how much each customer has on order.

To add grouping and totaling to the Classic report layout

  1. In Report Designer for report 55551, select the Sales Line data item and on the View menu, click Properties.

  2. In the Value field of the GroupTotalFields property, enter the name of the field that you want to use to group the records. For this report, use the No. field.

  3. In the Value field of the DataItemTableView property, select a key that contains the field to group by. For this report, create a secondary key that consists only of the No. field in the Sales Line table. For more information, see How to: Define Primary and Secondary Keys.

    Note Note

    This step is required because the fields in the GroupTotalFields property must also be fields in an active key of the underlying table. If the key that you select is a composite key, then the grouping can fail if there are other fields in the key before the grouping field and the contents of one of these fields changes. You may have to create a distinct key for reports that access data in ways other than those used by your application in general. For more information, see GroupTotalFields Property.

  4. In the Value field of the TotalFields property, click the Assist button. In the Field List window, in an empty row, click the Lookup button to select the names of the fields for which totals should be calculated. For this report, on separate rows in the Field List window, select the Quantity and Line Amount fields. For more information, see TotalFields Property.

  5. Compile and save the report.

Expand image Adding Grouping and Totaling to the RDLC Report Layout in Visual Studio Report Designer

You have added grouping and totaling to the Classic report layout. Now, you will do the same for the RDLC report layout.

To add grouping and totaling to the RDLC report layout

  1. In the Classic client, on the View menu, click Layout to open the report in Visual Studio.

  2. Click any field in the table data region of the layout.

  3. Right-click the left handle of the any row in the table, and then click Insert Group.

  4. In the Grouping and Sorting Properties window, in the Name field, enter CustomerNo. This gives the group a name that is understandable and relates to the grouping field.

  5. In the Group on: section, in the Expression field, select =Fields!Customer__No__.Value and click OK. This groups the data by Customer.

  6. Right-click the left handle of any row in the table, and then click Insert Group.

  7. In the Grouping and Sorting Properties window, in the Name field, enter SalesLineNo.

  8. In the Group on: section, in the Expression field, select =Fields!Sales_Line_No_.Value, and then click OK. This groups data by item number in the Sales Line dataset.

  9. To add the total of the quantity, per customer, do the following:

    1. Right-click the Sales_Line_Quantity text box, and then click Expression.

    2. In the Expression window, enter the following expression: =SUM(Fields!Sales_Line_Quantity.Value), and then click OK.

  10. To add the total of the amount, per customer, do the following:

    1. Right-click the Sales_Line_Amount text box, and then click Expression.

    2. In the Expression window, enter the following expression: =SUM(Fields!Sales_Line_Amount.Value), and then click OK.

  11. Save the report in Visual Studio.

Expand image Running the Modified Report

In the Classic client, you must now save the modified report and compile it before you can run it.

To run the modified report

  1. In the Classic client, save the CustomerList report. A message informs you that the .rdlc file for this report has changed and asks if you want to load the changes. Click Yes to save the changes in the database.

  2. On the Tools menu, click Compile to compile the report.

  3. On the Windows taskbar, click Start, and then click Run.

  4. In the Run window, enter the following text: dynamicsnav:////runreport?report=55551, and then click OK.

  5. Click Preview to view the report.

Expand image See Also

Tasks

Walkthrough: Designing a Customer List Report
How to: Make a Report Available in the RoleTailored Client
Walkthrough: Designing a Report with Images, Interactive Sorting, and Visibility Toggle
Walkthrough: Creating a Link from a Report to a Page

Concepts

Designing Reports for the RoleTailored Client


Walkthrough: Modifying the Customer - Top 10 List Report

Walkthrough: Modifying the Customer - Top 10 List Report

This walkthrough demonstrates how to create a new client report definition (RDLC) report layout for the Classic report 111, Customer - Top 10 List. It also demonstrates how to modify the report in Visual Studio Report Designer. After completing this walkthrough, the RDLC report layout that you create will look similar to the RDLC report layout for report 111 that is in the CRONUS International Ltd. demo database.

In Microsoft Dynamics NAV 2009, you create RDLC report layouts with Report Designer in the Classic client and Visual Studio Report Designer. You can take advantage of several features in Visual Studio Report Designer that are not available for Classic report layouts.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Formatting text in Visual Studio Report Designer.

  • Adding color to an RDLC report layout.

  • Interactively sorting data in an RDLC report layout.

  • Adding a pie chart and a bar chart to a report.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Visual Studio. For more information about versions of Visual Studio that you can use, see Requirements for Developing Reports for the RoleTailored Client.

  • A new layout suggestion for report 111, Customer - Top 10 List. For more information, see How to: Create a Layout Suggestion.

Expand image Story

Viktor is a Microsoft Certified Partner working for CRONUS International Ltd. He has been asked to improve the look and feel of the default RDLC report layout for the Customer - Top 10 List report. He plans to use the capabilities that are available in Visual Studio Report Designer to:

  • Format data in the report.

  • Add background colors to the header and data rows.

  • Add a pie chart and a bar chart to the report.

  • Save the report in PDF format so that users who do not have the RoleTailored client installed can view the report.

  • Add functionality to the report so that you can click a customer name and jump to the customer card page in the RoleTailored client for the selected customer.

Expand image Formatting Text

In the following procedure, you format header and footer rows as bold, modify the font size of text boxes, and delete columns that are not necessary in the new report. In Visual Studio Report Designer, you can select multiple text boxes and set a property on all of them at the same time.

To format text in Visual Studio Report Designer

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select report 111, and then click Design.

  3. On the View menu, click Layout.

  4. In Visual Studio, in the Body section of the report layout, right-click the first column, which displays the rank, and then click Delete Columns.

  5. In the Body section of the report layout, right-click the fifth column, which displays the portion of balance, and then click Delete Columns.

  6. In the Body section of the report layout, select the four remaining fields in the header row of the table data region.

  7. On the View menu, click Properties Window.

  8. In the Properties window, expand Font.

  9. In the FontSize field, enter 9pt. In the FontWeight field, select Bold from the drop-down list.

  10. In the Body of the report layout, select the three fields in the first footer row.

  11. In the Properties window, expand Font.

  12. In the FontSize field, enter 9pt. In the FontWeight field, select Bold from the drop-down list.

  13. For every text box in the report that is not hidden:

    1. Select the text box.

    2. On the View menu, click Properties Window.

    3. In the Properties window, expand Font. In the FontSize field, enter 9pt.

  14. On the File menu, click Save Report.rdlc.

Expand image Adding Color

In the following procedure, you add color to the report. Adding a color to a whole row is a new capability in Microsoft Dynamics NAV 2009 RDLC report layouts. In Microsoft Dynamics NAV 2009, you can also apply a property based on conditions. For example, you can specify that odd and even rows have different background colors.

To add color to an RDLC report layout

  1. In Microsoft Visual Studio, select the fields in the header row in the table data region of the layout.

  2. On the View menu, click Properties Window.

  3. In the Properties window, in the BackgroundColor field, select RoyalBlue.

  4. In the table data region of the layout, select each field in the data row.

  5. In the Properties window, in the BackgroundColor field, expand the drop-down list. On the Web tab, select <Expression>.

  6. In the Edit Expression window, enter the following expression, and then click OK.

    CopyCode image Copy Code
    =IIF(RowNumber(Nothing) mod 2, "AliceBlue", "White")

    For more information, see Adding Style and Formatting to a ReportViewer Report.

  7. On the File menu, click Save Report.rdlc.

Expand image Adding Interactive Sorting

In the following procedure, you enable dynamic sorting for each column in the report table. After you design the report to include dynamic sorting, a user can preview the report and change the data sort order before printing the report.

To add interactive sorting to an RDLC report layout

  1. In Visual Studio, in the Body section of the report layout, right-click the first field in the first column, which displays the customer number header, and then click Properties.

  2. In the Textbox Properties window, click the Interactive Sort tab.

  3. On the Interactive Sort tab, select Add an interactive sort action to this textbox.

  4. In the Sort expression field, select =Fields!Customer__No__.Value from the drop-down list, and then click OK.

  5. Repeat steps 1 through 4 for each column. Select the following fields for the Sort expression field:

    • =Fields!Customer_Name.Value

    • =Fields!Customer__Sales__LCY__.Value

    • =Fields!Customer__Balance__LCY__.Value

Expand image Adding Charts

In the following procedure, you add a pie chart to display either the sales data or the balance data. For more information about using Visual Studio Report Designer to add charts to a report, see Adding Charts to a Report (Visual Studio Report Designer).

Note Note

The request page for report 111 allows you to specify whether to display sales data or balance data and whether to display a pie chart or a bar chart. Creating this request page is out of the scope of this walkthrough. You can use the request page for report 111 that is in the CRONUS International Ltd. demo database. This request page is not modified when you modify the RDLC report layout.

To add a pie chart

  1. In Visual Studio, on the View menu, click Toolbox.

  2. Drag a chart from the toolbox to the Body of the report layout below the table data region. Resize and place the chart.

  3. Right-click the chart, point to Chart Type, point to Pie, and then click Simple Pie.

  4. Right-click the chart, and then click Properties.

  5. In the Chart Properties window, on the Data tab, in the Dataset name field, select DataSet_Result from the drop-down list.

  6. Next to Values, click Add.

  7. In the Edit Chart Value window, click the Values tab.

  8. In the Edit Chart Value window, next to the Series label field, click the Function button to add an expression.

  9. In the Edit Expression window, add the following expression.

    CopyCode image Copy Code
    =IIF(Fields!ShowTypeNo.Value = 0,Fields!Customer__Sales__LCY__Caption.Value,Fields!Customer__Balance__LCY__Caption.Value)

    This expression specifies whether the label displayed in the legend of the pie chart contains the caption for Sales data or Balance data.

    Note Note

    In the request page, the user specifies whether to display sales or balance data in the chart. The ShowTypeNo variable is set by code on the request page. Transforming the request page is out of the scope of this walkthrough.

  10. In the Edit Chart Value window, next to the Value field, click the Function button to add an expression.

  11. In the Edit Expression window, add the following expression.

    CopyCode image Copy Code
    =IIF(Fields!ShowTypeNo.Value = 0,Fields!Customer__Sales__LCY__.Value,Fields!Customer__Balance__LCY__.Value)

    This expression specifies whether the data displayed in the pie chart is Sales data or Balance data.

  12. In the Edit Chart Value window, click OK.

  13. In the Chart Properties window, next to the Category groups field, click Add to group the data by customer so that each customer in the report is grouped in a unique section of the pie chart.

  14. In the Grouping and Sorting Properties window, on the General tab, under Group on, select the following value from the drop-down list.

    CopyCode image Copy Code
    =Fields!Customer__No__.Value

  15. In the Label field, select the following value for the label that is displayed in the legend.

    CopyCode image Copy Code
    =Fields! Customer__No__.Value

    This expression specifies that the customer number is displayed to show which customer is associated with a given color in the pie chart.

  16. In the Chart Properties window, on the Legend tab, under Layout, select Table. Under Position, change the position of the legend to the bottom middle position.

  17. In the body of the report layout, select the pie chart.

  18. On the View menu, click Properties Window.

  19. In the Properties window, expand Visibility.

  20. In the Hidden field, select <Expression> from the drop-down list.

  21. In the Edit Expression window, add the following expression.

    CopyCode image Copy Code
    =IIF(Fields!ChartTypeNo.Value = 1,FALSE,TRUE)

    This expression specifies whether to display the pie chart.

    Note Note

    In the request page, the user specifies whether to display a pie chart or a bar chart. The ChartTypeNo variable is set by code on the request page. Transforming the request page is out of the scope of this walkthrough.

  22. On the File menu, click Save Report.rdlc.

In the following procedure, you add a bar chart to display either the sales data or the balance data.

To add a bar chart

  1. In Visual Studio, on the View menu, click Toolbox.

  2. Drag a chart from the toolbox to the Body section of the report layout below the pie chart. Resize and place the chart.

  3. Right-click the chart, point to Chart Type, point to Bar, and then click Simple Bar.

  4. Right-click the chart, and then click Properties.

  5. In the Chart Properties window, on the Data tab, in the Dataset name field, select DataSet_Result from the drop-down list.

  6. Next to Values, click Add.

  7. In the Edit Chart Value window, click the Values tab.

  8. In the Edit Chart Value window, next to the Series label field, click the Function button to add an expression.

  9. In the Edit Expression window, add the following expression.

    CopyCode image Copy Code
    =IIF(Fields!ShowTypeNo.Value = 0,Fields!Customer__Sales__LCY__Caption.Value,Fields!Customer__Balance__LCY__Caption.Value)

    This expression specifies whether the label that is displayed in the legend of the bar chart is the Sales label or Balance label.

    Note Note

    In the request page, the user specifies whether to display sales or balance data in the chart. The ShowTypeNo variable is set by code on the request page. Transforming the request page is out of the scope of this walkthrough.

  10. In the Edit Chart Value window, next to the Value field, click the Function button to add an expression.

  11. In the Edit Expression window, add the following expression.

    CopyCode image Copy Code
    =IIF(Fields!ShowTypeNo.Value = 0,Fields!Customer__Sales__LCY__.Value,Fields!Customer__Balance__LCY__.Value)

    This expression specifies whether the data displayed in the bar chart is Sales data or Balance data.

  12. In the Edit Chart Value window, click OK.

  13. In the Chart Properties window, next to the Category groups field, click Add to group the data by customer so that each customer in the report is grouped in a separate bar in the chart.

  14. In the Grouping and Sorting Properties window, on the General tab, under Group on, select the following value from the drop-down list.

    CopyCode image Copy Code
    =Fields!Customer__No__.Value

  15. In the Label field, select the following value for the label that is displayed next to each bar in the chart.

    CopyCode image Copy Code
    = Fields!Customer__No__.Value

    This expression specifies that the customer number is displayed to show which customer is associated with a given bar in the bar chart.

  16. In the Grouping and Sorting Properties window, on the Sorting tab, under Sort on, select <Expression> from the drop-down list.

  17. In the Edit Expression window, add the following expression.

    CopyCode image Copy Code
    =IIF(Fields!ShowTypeNo.Value = 0,Fields!Customer__Sales__LCY__.Value,Fields!Customer__Balance__LCY__.Value)

  18. In the Grouping and Sorting Properties window, under Direction, select Ascending from the drop-down list, and then click OK.

  19. In the Chart Properties window, on the Legend tab, under Position, change the position of the legend to the bottom middle position.

  20. In the body of the report layout, select the bar chart.

  21. On the View menu, click Properties Window.

  22. In the Properties window, expand Visibility.

  23. In the Hidden field, select <Expression> from the drop-down list.

  24. In the Edit Expression window, add the following expression.

    CopyCode image Copy Code
    =IIF(Fields!ChartTypeNo.Value = 0,FALSE,TRUE)

    This expression specifies whether to display the bar chart.

    Note Note

    In the request page, the user specifies whether to display a pie chart or a bar chart. The ChartTypeNo variable is set by code on the request page. Transforming the request page is out of the scope of this walkthrough.

  25. On the File menu, click Save Report.rdlc.

Expand image Next Steps

Now that you have completed this walkthrough, your Customer - Top 10 List report has an RDLC report layout that takes advantage of features in Visual Studio Report Designer. Your RDLC report layout includes color, dynamic sorting, and charts. The next steps are to:

  • Create a link from each customer that is listed in this report to the customer card page. For more information, see Walkthrough: Creating a Link from a Report to a Page.

  • Learn about transforming request forms to request pages. For more information, see How to: Transform the Request Form.

Expand image See Also

Concepts

Designing Reports for the RoleTailored Client

Other Resources

RoleTailored Client Report Walkthroughs


Designing Reports for the Classic Client

Designing Reports for the Classic Client

In Microsoft Dynamics NAV 2009, reports are used to print information from a database. A report can be used to structure and summarize information, and reports can be used to print documents such as invoices. Reports can also be used to process data without printing anything.

Designing Reports

In Microsoft Dynamics NAV, the design process is divided into several distinct phases that reflect the different aspects of creating a report.

  • Defining the data model—the tables and fields that the report is based on.

  • Defining the grouping and sum that the report will contain.

  • Defining the visual layout of the report.

When you define the data model you decide what tables and fields to base the report on. The next step is to define the grouping, sum, and filtering that the report must contain. These are important elements of report functionality and add value to the report. When designing a report for the RoleTailored client, you use Visual Studio to define how the data that is displayed in the report should be grouped as well as any totaling that should be performed. For more information, see Designing Reports for the RoleTailored Client.

See Also

Concepts

Report Fundamentals
What Are Reports?
The C/SIDE Report Designer
Saving, Compiling, and Running Reports


Report Fundamentals

Report Fundamentals

Reports are used to print information from a database. A report can be used to structure and summarize information, and reports can be used to print documents such as invoices. Reports can also be used to process data without printing anything.

The following sections introduce the fundamental concepts and basic tasks involved in designing reports. Designing reports for Classic and RoleTailored client is different. For more information, see Designing Reports for the RoleTailored Client and Designing Reports for the Classic Client.

See Also

Concepts

What Are Reports?
What Happens When a Report Runs?
The C/SIDE Report Designer
Saving, Compiling, and Running Reports
Designing Reports for the RoleTailored Client
Designing Reports for the Classic Client


What Are Reports?

What Are Reports?
See Also

Reports serve several purposes in Microsoft Dynamics NAV. The following describes the purpose of reports.

The Purpose of Reports

Reports are used to extract and print information from a database in a structured way. For example, you can create a report that lists all the customers and all the orders placed by each customer. To print an invoice, you must create a report that is automatically filled out with the relevant information.

Reports can also be used for tasks other than printing. A report can be used to automate many recurring tasks such as updating all the prices in an item list. You can do this by writing C/AL code in a codeunit, but using a report is much easier because you can take advantage of the powerful data modeling facilities available in the report designer.

See Also

Concepts

Report Fundamentals
Report Components
Logical and Visual Report Design


Report Components

Reports consist of several components. The following table describes how these components work.

Report Components

Component Description

Report Description

A complete description of the report including how data is collected, and how it is presented on paper when the report is run. The report description is stored in the database.

Data Item

Corresponds to a table. To retrieve information from tables, you define data items that refer to tables. When a report uses more than one table, you must set relations between the data items so that you can retrieve and organize the data the way that you want.

Section

In a report that is going to be printed, each data item has one or more sections. A section can be thought of as a block of information that should be printed. The complete report is composed of a number of sections. Some sections are printed only once, for example, headers. Other sections are printed for each record retrieved from the database. The information printed in the sections is composed of controls. The available controls are:

  • Text boxes – for printing the result of the evaluation of any valid C/AL expression, such as the contents of a table field (also used for complex calculations).

  • Labels – for printing static text such as a caption for a column of data.

  • Shapes, images and picture boxes – for printing graphical elements (lines, circles) and bitmap pictures.

Request form

A form that is run before the report starts to execute. You use request forms to enter requests and select options for the report, for example, the sort order or the level of detail that you want in the report.

Property

An attribute of an object such as a report, data item, section and so on. The attribute may be for example, color, size, and whether or not it is displayed. Properties are set in the Properties window of the object.

Trigger

Certain predefined events that cause the system to execute a user-definable C/AL function. The event triggers the function. The report itself, the data items, the sections, the request form, and the controls all have triggers.

See Also

Concepts

Report Fundamentals
What Are Reports?
Logical and Visual Report Design


Logical and Visual Report Design

Logical and Visual Report Design

You design a report by first defining the logical structure or data model, and then designing the visual layout.

Data Items

The report data model is built from data items that each correspond to a table. When the report is run, each data item is iterated for all the records in the underlying table. When a report is based on more than one table, you indent the data items to establish a hierarchy of data items and control how the information is gathered.

Example

To make a report that prints out a list of customers and lists the sales orders placed by each customer, you must define two data items. One data item corresponds to the Customer table and the other corresponds to the Sales Order table. The second data item, in this case the Sales Order table, should be indented. This means that as the report works through the records in the Customer table, each customer's sales orders are found by going through the records in the Sales Order table.

Defining the Data Model

  • You define the data model by defining how the data is collected. This includes:

  • Creating data items that define the tables that the report uses.

  • Defining the relationships between the data items if the report uses more than one table.

  • Defining the key, sort order, and filters to use with the data items.

  • Defining how data is grouped.

  • Defining how totals and subtotals are calculated.

  • Writing C/AL code in data item triggers, if necessary, to improve the functionality of the report.

Designing the Visual Layout

The visual layout of a report includes the sections. In a printing report (remember that reports do not actually have to print anything), one or more sections are attached to each data item.

There are several types of sections, each with a specific function. Normally, the bulk of the data is printed in the body section of a data item, while the header section is used to print information before any data item record is printed, for example, column captions. But some reports do not use the body section and all the information is printed in other sections.

See Also

Concepts

What Are Reports?
Report Components


The C/SIDE Report Designer

You use the C/SIDE Report Designer to create reports that you want to use in your application. The Report Designer contains two additional designers:

  • Section Designer, used for designing the layout of reports.

  • Request Options Form Designer, used for designing request options forms.

The C/SIDE Report Designer

You use the Report Designer window to define the data model by adding data items and indenting them appropriately. You can edit the properties and triggers for each of the data items by selecting the data item and opening the Properties window or the C/AL Editor, respectively. To edit the properties of the report itself, select an empty line in the Report Designer window and open the Properties window. To edit the triggers of the report itself, select an empty line in the Report Designer window and click View, C/AL Code. Alternatively, you can click Edit, and then click Select Object, and then open the Properties window or the C/AL Editor.

The Section Designer

After you have defined one or more data items, you can design the visual layout of the report in the Section Designer. You can use the Field Menu to select fields and place them in the sections as controls. You can think of each section as one or more lines on the paper that the report will eventually be printed on. A header section is printed only once, while a body section is typically printed several times as each loop of the report is iterated. You can control whether the header should be printed every time a page break occurs while the body sections of the same data item are being printed.

You can edit properties and triggers for each section by opening the Properties window or the C/AL Editor, respectively, while the section is selected. The controls you place in the sections have a subset of the properties that controls have on forms, not all the properties are relevant for a report. You can use the same tools to modify the properties (the Font Tool, the Color Tool). You can see a list of the properties in the Properties window.

The Request Options Form Designer

You use the Request Options Form Designer to create a form with fields that prompt the user to select some options before running the report. This designer works like Form Designer.

Designing Reports for the RoleTailored Client

Designing reports that will run on the RoleTailored client is different. For more information, see Designing Reports for the RoleTailored Client.

See Also

Concepts

Report Fundamentals
What Are Reports?
What Happens When a Report Runs?
Saving, Compiling, and Running Reports
Designing Reports for the RoleTailored Client

© 2010 Microsoft Corporation. All rights reserved.


What Happens When a Report Runs?

What Happens When a Report Runs?
See Also

This section explains what happens when you run a report.

Note Note

Running reports on the RoleTailored client is different. For more information, see Designing Reports for the RoleTailored Client.

When a Report Runs

When you initiate the report run, the OnInitReport trigger is called. This trigger performs any processing that is necessary before the report is run. It can also stop the report. If the OnInitReport does not end the processing of the report, the request form for the report is run, if it is defined. Here, you select the options that you want for this report. You can also decide to cancel the report run. If you decide to continue, the OnPreReport trigger is called. At this point, no data has yet been processed. When the OnPreReport trigger has been executed, the first data item is processed provided that the processing of the report was not ended in the OnPreReport trigger.

When the first data item has been processed, the next data item, if there is any, is processed in the same way. When there are no more data items, the OnPostReport trigger is called to do any necessary post processing, for example, removing temporary files.

How a Data Item is Processed

Before the first record is retrieved, the OnPreDataItem trigger is called, and after the last record has been processed, the OnPostDataItem trigger is called.

Between these two triggers, the data item records are processed. Processing a record means executing the record triggers and outputting sections. C/SIDE also determines whether the current record should cause the outputting of a special section, such as a header, footer, group header or group footer.

If there is an indented data item, a data item run is initiated for this data item (data items can be nested 10 levels deep).

When there are no more records to be processed in a data item, control returns to the point from which processing was initiated. For an indented data item, this means the next record of the data item on the next highest level. If the data item is already on the highest level indentation is zero control returns to the report.

See Also

Concepts

Report Fundamentals
What Are Reports?
The C/SIDE Report Designer
Saving, Compiling, and Running Reports
Designing Reports for the RoleTailored Client


Saving, Compiling, and Running Reports

Saving, Compiling, and Running Reports

After you have designed a report, you must save and compile it before it can be run. Normally, you do this after you finish designing the report. However, you may want to save a report that is not yet finished and therefore cannot be compiled, for example, if the report contains C/AL code that is incomplete. You can also test compiling a report without closing or saving it.

Working with reports that will display in the RoleTailored client is different. For more information, see Designing Reports for the RoleTailored Client.

Saving and Compiling a Report

A report is closed when the Report Designer window is closed. When you close a report, you are prompted to decide whether or not the report should be saved. If it is a new report, you must give it an ID and a name. The ID must be unique and follow the rules for numbering objects - your local Microsoft Certified Business Solutions Partner can provide you with this information.

If you enter ID and Name as report properties, these values are used, and you are not prompted for an ID and a name when you close the report.

The Compiled option field is set to TRUE by default. If your report is not yet ready to be compiled, clear the check mark, and click OK to save the report.

You can save a report without closing it by clicking File, and then Save or Save As. By using Save As, you can rename an existing report. Like all the other objects in C/SIDE, reports must be compiled before they can be run. When you are designing a report, you might want to test compiling it to find any errors that it may contain (this is more important when the report contains C/AL code in triggers). To test compiling a report when you are designing it, click Tools, and then Compile.

Running a Report

In the application, your reports can be incorporated into menus, or they can be called from, for example, a command button on a form. However, when you are designing reports, you will often want to run them before they are integrated into the application. When you are designing a report, you can test running the report by clicking File, and then Run. The report is compiled and run in its current stage of development. It is not saved, which means that you can use this function to verify that the changes you are making work as intended before you save them. You can run a report from the list of reports in the Object Designer window by selecting a report, and then clicking the Run button.

See Also

Concepts

Report Fundamentals
What Are Reports?
What Happens When a Report Runs?
The C/SIDE Report Designer
Designing Reports for the Classic Client
Designing Reports for the RoleTailored Client


Report Properties Overview

Report Properties Overview

Properties are a feature which can be found in every application object. This topic provides an overview of the report properties.

Properties

Properties | Select properties by
The report | Clicking an empty line in Report Designer or by clicking Edit, and then Select Object.
Data items | Clicking the data item in the Report Designer window.
Sections | Clicking either the section bar or somewhere in the section (not on a control.)
Controls in a section | Clicking the control.

When an object is selected, click View, and then click Properties to open the Properties window. You can set the value of each property in the Value field. When you leave this field (by pressing ENTER or by moving with the arrow keys), the property is updated. Default values are displayed in angle brackets (<>). You can reset any property to its default value by deleting the current value and then moving out of the field. This only applies to properties that have a default vale.

How Properties Are Inherited

Controls that have a direct relationship to table fields inherit the settings of those properties that are common to the field and the control. For example, if you have an accounting application that stores calculated amounts with five decimal places (for precision), but on a printed report, you only want to display currency amounts with the usual number of decimal places. You can change the DecimalPlaces property of the text box control to display fewer decimals than the default (but not more).

See Also

Concepts

Report Properties
Data Item Properties
Section Properties


Report Properties

Report Properties

This topic briefly describes the report properties. To open the Properties window of a report, select an empty line in Report Designer or click Edit, click Select Object, and click View, and then click Properties.

Properties

The following table lists the general report properties. For more information, see C/SIDE Reference Guide.

Property | Description
ID | ID of the report. Must be unique among reports.
Name | Name of the report.
Caption | Caption (shown on the Request Form window, for example). The default is the same as Name.
CaptionML | The translation of the caption.
ShowPrintStatus | Determines whether the printing status window should be displayed during printing (with the opportunity to cancel printing).
UseReqForm | Determines whether the request form should be run before the report.
UseSystemPrinter | If Yes, then the system default printer is used to print the report. If No, then the printer defined for the combination User/Report in the setup is used.
ProcessingOnly | If No, the report is a processing only report. If Yes, the report cannot have sections.
TransactionType | The behavior of a transaction takes effect from the beginning of a transaction. There are four basic transaction type options: Browse, Snapshot, UpdateNoLocks, and Update. There is a Report option that maps to one of the basic options and enables a report to use the most concurrent read-only form of data access. When you use Classic Database Server, it maps to Snapshot. When you use SQL Server, it maps to Browse.
Description | For internal purposes.
TopMargin | Top margin in 1/100 mm.
BottomMargin | Bottom margin in 1/100 mm.
LeftMargin | Left margin in 1/100 mm.
RightMargin | Right margin in 1/100 mm.
HorzGrid | Distance between horizontal gridlines (1/100 mm).
VertGrid | Distance between vertical gridlines (1/100 mm)
Permissions | The permissions of the report to access database objects. (The report can have wider permissions than the individual user, thereby enabling the user to print reports which retrieve information from tables normally cannot be accessed.)
Orientation | Sets the page orientation for the report, Portrait or Landscape.
PaperSize | Sets the paper size for the report.
PaperSourceFirstPage | Specifies the paper source to use for printing the first page of the report. This is useful if the report has a cover.
PaperSourceOtherPage | Specifies the paper source to use for the remaining the pages in the report
DeviceFontName | Use this property for reports that are designed specifically for dot matrix printers, to prevent the printer from switching into graphics mode when printing text. Specify the name of a device font (a font that is built into a printer).

See Also

Concepts

Data Item Properties
Section Properties


Data Item Properties

Data Item Properties

A report data model consists of data items. This topic lists the properties for data items.

Properties

The following table lists the properties for data items. For more information, see C/SIDE Reference Guide.

Property | Description
DataItemIndent | The indentation level, which can be set in the designer when creating data items.
DataItemTable | The table that the data item is based on, which can be set in the designer when creating data items.
DataItemTableView | The key, sort order, and filters to apply.
DataItemLinkReference | The DataItemVarName of a less-indented data item that this data item will be linked to.
DataItemLink | Link between the current data item and the data item specified by DataItemLinkReference.
NewPagePerGroup | Determines whether each group should be printed on a separate page.
NewPagePerRecord | Determines whether each record should be printed on a separate page.
ReqFilterHeading | The caption for the request form tab that relates to this data item. The default is the name of table that the data item is based on.
ReqFilterHeadingML | Translation of the caption for the request form tab.
ReqFilterFields | Name of the fields that will be included in the request filter form.
TotalFields | Name of the fields for which totals will be calculated.
GroupTotalFields | Name of the fields that will be used for grouping data.
CalcFields | Name of the fields that will be calculated after a record has been retrieved.
MaxIteration | Maximum number of data item loop iterations.
DataItemVarName | Name of record as a variable. The default is the name of table that the data item is based on.
PrintOnlyIfDetail | Print item only if sublevels generate output.

See Also

Concepts

Report Properties
Section Properties


Section Properties

Section Properties

In a report, each section holds a different set of controls. This topic briefly describes the section properties.

Properties

The following table lists the section properties. For more information, see C/SIDE Reference Guide.

Property | Description
PrintsOnEveryPage | Determines whether the header and footers should be printed on every page.
PlaceInBottom | Determines whether the footer should be placed below the last line or at the bottom of the page.
SectionWidth | Width in 1/100 mm.
SectionHeight | Height in 1/100 mm.

See Also

Concepts

Report Properties
Data Item Properties


Types of Reports

Types of Reports

In this section, you will learn about the types of reports that are found in a functional area.

List Reports

A list report contains a single data item that corresponds to the table that is listed. The table can either be a master table or a supplemental table. Each column contains a field from the table. The data is printed from that table, instead of from other tables or calculated from other tables. The name of the report is usually the name of the table followed by the word "List". Examples of list reports are:

  • Customer - List

  • Insurance - List

  • Vendor - List

Test Reports

A test report is a report that is printed from a journal table. Its purpose is to test each of the lines in the journal according to the same criteria that will be used for posting. This ensures that any errors that exist can be found and fixed before the lines are posted. This is useful because if an error is found during posting, processing stops and the error must be fixed before posting can be resumed. Running a test report is a good way to identify these errors. The name of the report is usually the name of the corresponding journal form followed by the word "Test". Examples of test reports are:

  • General Journal - Test

  • Resource Journal - Test

Posting Reports

A posting report can be printed as part of the "post and print" option on a journal. This report is printed from the register and has the same name as that register. It lists all the transactions, that is, ledger entries, which have been posted into that register. Examples of posting reports are:

  • G/L Register

  • Vendor Register

Transaction Reports

A transaction report contains two data items. The first data item is a master table, and the second is the corresponding ledger table. Usually, a transaction report lists all of the ledger entries for each record in the ledger table. There is a subtotal for each master table record, and a grand total for all the tables that are printed.

This type of report is used to view all the transactions for a particular master record. There is no standard name for this kind of report. Examples of transaction reports are:

  • Trial Balance

  • Vendor - Trial Balance

Other Reports

Reports are more loosely defined than other application objects because they are often customized for a particular client. However, most reports consist of a tabular list with records listed horizontally and each field displaying in its own column. There is often a group heading or total to split the lines among various categories and subtotal the lines according to the categories. Examples of other reports are:

  • Vendor Information

  • Item Sales by Customer

Document Reports

Document reports are different from other reports, in that, many of the fields are not displayed in columns. An example of a document report is an invoice, where the header information is printed as though filling out an invoice document and this information is repeated at the top of each page. No page contains information from more than one header. The lines for the invoice are printed like a standard report in rows and columns. The lines correspond to the header on the same page, and lines from different invoices are not displayed on the same page. Examples of document reports are:

  • Sales Invoice Numbers

  • Purchase Invoice Numbers


Types of Report Sections

Types of Report Sections

A report contains a number of sections that can be used to contain data.

Report Sections

The following table lists the different report sections.

Section name Output

Header

Prints before a data item loop begins. If the PrintOnEveryPage property of the section is set to Yes, the header is also printed on each new page.

Body

Prints for each iteration of the data item loop. When there is an indented data item, the complete loop for this data item begins after the body section of the higher level data item has been printed.

Footer

Prints after the loop has finished. If the PrintOnEveryPage property of the section is set to Yes, the footer is also printed on each new page.

If the PlaceInBottom property of the section is set to Yes, the footer section is printed at the bottom of the page, even if the data item loop ends in the middle of a page.

GroupHeader

A new group starts.

GroupFooter

A group ends.

TransportHeader

Prints if a page break occurs during a data item loop, the header is printed at the top of the new page. This section is printed after any header section of the data item.

TransportFooter

Prints ff a page break occurs during a data item loop, the header is printed before the page break This section is printed before any footer section of the data item.

See Also

Concepts

Request Forms
Report, Section, and Data Item Triggers
Types of Reports


Request Forms

Request Forms

Request forms are used in connection with reports to let the end-user specify search criteria and filtering in a report.

Filtering on Request Forms

On a new report, the fields that you define as ReqFilterFields are shown, but you can determine if you want to place a filter on other fields by adding lines below those already used.

Note Note

Remember that users can choose to set filters on fields which you did not specify. We recommend that you add fields that the users of the report will frequently set filters on. You should always strive for balance in your design. If the table has a lot of fields, inexperienced users may find it difficult to find the relevant fields that they want to set filters on.

To remove the tab where you set the filters, do not define any ReqFilterFields for the data item and set the DataItemTableView to define a sort order. If you create a request options form, it will still be shown.

If there is no request options form, an empty form is displayed. On this form, users can choose options such as Print and Cancel. If you set UseReqForm to No, the report will start printing as soon as it is run. In this case, users cannot cancel the report run. It will still be possible to cancel the report, but some pages may still print. If a DataItemTableView is not defined, users can select the key and sort order at runtime.

Be careful what you allow users to change. In complex report that involves data from several tables, the functionality may depend on a specific key and sort order. Letting the user choose filters freely does not interfere with the logic of the report.

See Also

Tasks

Walkthrough: Designing a Simple Report

Concepts

Types of Report Sections


Classic Report Walkthroughs

Classic Report Walkthroughs

This section lists the available walkthroughs for Classic reports.

In This Section

Documentation | Description
Walkthrough: Creating a Nonprinting Report | This walkthrough illustrates how and when to create a report that is not used for printing purposes.
Walkthrough: Creating a Simple Document | This walkthrough describes how to use Report Designer to create a simple sales invoice.
Walkthrough: Designing a Simple Report | This walkthrough illustrates how to design a simple customer list report based on the Customer table.
Walkthrough: Designing a More Advanced Report | This walkthrough describes how to design reports that are based on more than one table.
Walkthrough: Designing a Report with Grouping and Totaling | This walkthrough illustrates how to design a report that contains grouping and totaling to enhance the understanding of report data.
Walkthrough: Creating Advanced Sample Reports | This walkthrough includes examples of reports that are more complex. These examples are not intended to be complete or ready to run, but are meant to give you examples that might be useful when designing your own reports.

See Also

Concepts

Designing and Maintaining Reports
Designing Reports for the Classic Client


Walkthrough: Creating a Nonprinting Report

Walkthrough: Creating a Nonprinting Report

In this walkthrough, you will create a non-printing report. Although you can achieve the same functionality by writing a codeunit, there are several reasons for using non-printing reports:

  • The functionality that is available through a request form that prompts for options and filters is achieved with less effort than recreating the functionality in a codeunit using C/AL code.

  • Using the features of Report Designer to prompt for options and to set filters ensures consistency in the application that you are creating.

  • Instead of writing C/AL code to open tables and retrieve records, you only need to define a data item.

This report is simple—it adjusts prices in the Item table. Users can set filters on fields in the table to select a range of items by number, posting group, or vendor, and then choose the factor by which to adjust the prices.

Expand image Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

Expand image Defining the Data Model

This report has one data item that is based on the Item table.

To define the data model

  1. Open Report Designer and create a new blank report.

  2. Create a data item based on the Item table.

  3. Open the Properties window of the report and set the value of the ProcessingOnly property of the report to Yes.

  4. Open the Properties window of the data item and use the AssistButton to set the value of the DataItemTableView property to No..

    Note Note

    Though this is not necessary for the functionality of the report, it removes the Sort button from the request form that is presented to the user when they want to run the report.

  5. Use the AssistButton in the ReqFilterFields property to select the fields that the users can filter by.

  6. Declare the following variables

    Name Datatype Description

    Window

    Dialog

    Prints a screen message.

    Adjustment

    Decimal

    Used for the value that the user enters in the request form.

    NewPrice

    Decimal

    Used to store an intermediate result.

Expand image Creating a Request Form

In the previous procedure you created a request form that contains a tab where you can set filters on some of the fields in the data item. You must now add an Options tab, where you can define the adjustment factor.

To create an options tab

  1. Click View, and then click Request Form to open Request Options Form Designer.

  2. Add a text box with a label to the form. To have the label added automatically, click the Add Label button in the Toolbox before selecting the Text Box tool.

  3. In the Properties window of the text box, set the value of the SourceExpr property to Adjustment, the variable you have just created.

Expand image Using the Triggers

Now that you have defined the data model and designed the request form, you need to add C/AL code to the triggers of the Item data item to perform the actual price adjustment.

To use the triggers

  1. Open C/AL Editor.

  2. In the OnPreDataItem() trigger, enter the following lines of code.

    CopyCode image Copy Code
    Window.OPEN('Processing item #1#########');
If Adjustment = 0 THEN
CurrReport.QUIT;

  3. In the OnAfterGetRecord() trigger, enter the following lines of code.

    CopyCode image Copy Code
    Window.UPDATE(1,"No.");
NewPrice := Adjustment x "Unit Price";
VALIDATE("Unit Price", NewPrice):
MODIFY;

  4. Close the C/AL Editor window and save the report.

The code that you added to the triggers works like this:

  • The first statement in the OnPreDataItem trigger opens a progress window that shows the progress of the report as it is run. Because the report is non-printing, the usual printing progress window is not shown. If the table is large, the report may run for a while. Therefore, it is a good idea to tell the user that something is happening and show them how it is progressing.

  • The first statement in the OnAfterGetRecord trigger enters the item number in the window each time a new record has been retrieved.

  • The second statement in the OnPreDataItem ends the report without doing any processing if the adjustment factor is 0 (zero). If the adjustment factor were allowed to be zero, all the prices in the table would be set to zero. The statement used here is a crude way of handling this. In a more polished version, you would, for example, have a chance to reenter the adjustment factor (or be notified of the reason for quitting the report).

  • The last three lines in the OnAfterGetRecord trigger update the prices. First, the adjusted value is assigned to the NewPrice variable. Then, the VALIDATE function of the Unit Price field is used to update the price. Any special processing (for example, updating of related fields) in the OnValidate trigger of the table field is performed. Finally, the MODIFY function is used to commit the change.

Expand image See Also

Tasks

Walkthrough: Designing a Simple Report
Walkthrough: Designing a More Advanced Report

Concepts

Designing Reports for the Classic Client


Walkthrough: Creating a Simple Document

Walkthrough: Creating a Simple Document

In this walkthrough you will learn how to use Report Designer to create a document. The example used is a simple sales invoice that does not take the complexities of VAT calculations into account and does not test a number of conditions that would have to be tested in a real-life situation. Furthermore, it does not print all the information you would expect to find on an invoice.

Expand image Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

Expand image Defining the Data Model

The two primary tables used in creating a sales invoice are the Sales Invoice Header and the Sales Invoice Line tables. Two supporting tables, Payment Terms and Shipment Method, are used to expand the code used in the invoice tables to more descriptive text. The Company Information table is used to retrieve information about the company that is preparing the invoice.

The Sales Invoice Header table contains general information about each sales invoice that has been posted, while the Sales Invoice Line table contains the individual lines that make up each invoice. The tables are related through a field called No. in the header table (the primary key of this table) and Document No. in the lines table.

To define the data model

  1. Open Object Designer and create a new blank report.

  2. In Report Designer, create a data item based on the Sales Invoice Header table.

  3. Create another data item based on the Sales Invoice Line table, and indent this data item one level.

  4. Open the Properties window of the Sales Invoice Line data item. By default, the DataItemLinkReference property of the Sales Invoice Line data item points to the Sales Invoice Header data item. Leave it like this, and set the value of DataItemLink property to Document No.=FIELD(No.).

  5. Enter the Amount field as the value of the TotalFields property of the Sales Invoice Line data item. This calculates the total amount for all the lines in the invoice.

  6. Finally, change to the Properties window of the Sales Invoice Header data item. Enter the No. field as the value of the ReqFilterFields property. This lets the users of the report select a posted invoice to print.

Expand image Creating the Variables

The data model has now been defined. In this report, some supporting variables are needed to access information from tables that cannot be fitted into the data model.

To create the variables

  1. Click View, and then click C/AL Globals.

  2. Declare the following variables in the C/AL Globals window.

    Name DataType Subtype Length

    CompInfo

    Record

    Company Information

    PaymentTerms

    Record

    Payment Terms

    ShipmentMethod

    Record

    Shipment Method

    CustAddr

    Text

    30

    CompAddr

    Text

    30

  3. The two last variables must be declared as arrays. Open the Properties window of each variable and set Dimensions to 6 for the CustAddr variable and to 4 for the CompAddr variable.

The data model has now been defined. Next, you need to add C/AL code to the report triggers.

Expand image Writing Code for the Triggers

This basic version of the report needs a very limited amount of C/AL code in order to function correctly. The code must be entered in the triggers of the Sales Invoice Header data item.

To write code for the triggers

  1. Select the Sales Invoice Header data item, click View, and then click C/AL Code.

  2. In the OnPreDataItem() trigger, enter the following lines of code.

    CopyCode image Copy Code
    CompInfo.GET;
CompAddr[1] := CompInfo.Name;
CompAddr[2] := CompInfo.Address;
CompAddr[3] := CompInfo."Address 2";
CompAddr[4] := CompInfo.City;
COMPRESSARRAY(CompAddr);

  3. In the OnAfterGetRecord() trigger, enter the following lines of code.

    CopyCode image Copy Code
    CustAddr[1] := "Bill-to Name";
CustAddr[2] := "Bill-to Name 2";
CustAddr[3] := "Bill-to Contact";
CustAddr[4] := "Bill-to Address";
CustAddr[5] := "Bill-to Address 2";
CustAddr[6] := "Bill-to City";
COMPRESSARRAY(CustAddr);
PaymentTerms.GET("Payment Terms Code");
ShipmentMethod.GET("Shipment Method Code")

The code in the OnPreDataItem trigger works like this:

  • The first line, CompInfo.GET, retrieves a record, which is the only record from the Company Information table.

  • The next four lines assign the contents of a field in the record in the Company Information table to an element of the CompAddr array.

  • The final line of the OnPreDataItem trigger uses the COMPRESSARRAY function with the CompAddr array as an argument to eliminate empty elements from the array. You do this because you cannot be certain that all the fields in the retrieved record contain values. If you printed each field on a separate line, an empty field would cause an empty line to be printed.

The code in the OnAfterGetRecord trigger works like this:

  • The first six lines assign values from the record in the Sales Invoice Line data item to elements of the CustAddr array.

  • After this, COMPRESSARRAY is used to eliminate empty elements from the array as described earlier.

  • The last two lines use the GET function (with the code for Payment Terms and Shipment Method from the Sales Invoice Header record as arguments) to retrieve the related records from the Payment Terms and Shipment Method tables. When you design the sections, the full text descriptions can then be extracted from these records.

Expand image Designing the Sections

Now that you have defined the data model and added C/AL code to retrieve supporting information, you can design the sections. For information about how to design sections in a report, see Walkthrough: Creating Advanced Sample Reports.

Expand image See Also

Tasks

Walkthrough: Creating Advanced Sample Reports

Concepts

Designing Reports for the Classic Client


Walkthrough: Creating Advanced Sample Reports

Walkthrough: Creating Advanced Sample Reports

This walkthrough includes examples of reports that are more complicated than those described in earlier walkthroughs. These examples are not intended to be complete or ready to run, but are meant to give you examples that might be useful when designing your own reports.

Expand image Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

Expand image Using Virtual Tables as the Data Model

C/SIDE includes a number of virtual tables, such as the Integer table and the Date table. The Date table consists of five fields: Period Type, Period Start and Period End, Period No. and Period Name. Period Type can be Date, Week, Month, and so on. Period Start is the starting date of each period and Period End is the last date in the period. Period End dates are closing dates.

In this example, the Date table is used to create a report that prints information from the Cust. Ledger Entry table. For each day in a range of dates that can be chosen by the user when they want to run the report, the report summarizes the entries made on that date.

The report lists the different types of documents that were entered, the number of documents of each type, and the total number of documents entered on each date. The report also displays the total amount entered on each date. Finally, the total number of entries and the total amount entered for the selected date range is printed at the bottom of the report.

You could create the report by grouping the entries according to the Cust. Ledger Entry table alone, but the field that contains the posting date in that table is not part of any key. Creating a special key just for this report is not advisable, because it would slow down all the other transactions that involve this table. Every sales entry would be affected.

This data model contains two data items—one based on the Date table and one based on the Cust. Ledger Entry table.

To use virtual tables as the data model

  1. Open Report Designer and create a new blank report with two data items with the Date and the Cust. Ledger Entry tables as the underlying tables.

  2. Indent the Cust. Ledger Entry data item.

    Note Note

    Indenting the Cust. Ledger Entry data item ensures that the system only searches through the Cust. Ledger Entry table when a date is found in the Date table, that lies within the range specified by the user

  3. Select the Date data item and open the Properties window.

  4. In the Value field of the DataItemTableView property, click the AssistButton to open the Table View window.

  5. In the Table Filter field, click the AssistButton to open the Table Filter window.

  6. In the Table Filter window, set a filter that selects records with the Period Type of Date.

    Note Note

    This is an important step, as the iteration of the Date data item would otherwise run through all the records, including those for Weeks, Quarters, Months, and Years.

  7. Click OK in the Table Filter window. Click OK in the Table View window.

  8. In the Properties window of the Date data item, in the Value field of the ReqFilterFields property, enter Period Start. This lets the user enter a range of dates when they fill out the request form before running the report. This date range is then used to filter the information displayed in the report.

  9. Open the Properties window of the Cust. Ledger Entry data item. In the Value field of the DataItemTableView property, click the AssistButton to open the Table View window.

  10. In the Key field, use the AssistButton to open the Key List window.

    Note Note

    In this example, an appropriate key is a key that contains the Document Type field, as the definition of a group in this report is based on these fields. Here, a key is selected that has this field as its first component, the other fields that are included in the key are not important. No individual entries will be printed, so they do not need to be sorted in any specific way.

  11. Be sure that the DataItemLinkReference property points to the Date data item, this is the default value.

  12. In the DataItemLink property, you must specify the field that establishes the link between the two data items. In the Value field of the DataItemLink property, click the AssistButton to open the DataItem Link window.

  13. In the Field field, use the AssistButton to select the Posting Date field from the Cust. Ledger Entry data item. In the Reference Field field, select the Period Start field from the Date data item.

  14. In the Value field of the GroupTotalFields property, use the AssistButton to select the Document Type field.

    Note Note

    This groups the entries from the Cust. Ledger Entry table according to their document type: Payment, Invoice, Credit Memo, Finance Charge Memo, Reminder, or Refund.

  15. In the Value field of the TotalFields property, use the AssistButton to select the Amount field. This adds up the entries in the Amount field for each document type for the date in question.

Expand image Designing the Sections

So far, this report allows you select a range of dates from the request form of the report. The report runs through the Date table, with a constant filter on the Period Type field that selects only records whose type is Date. If you select a date range, only dates within this range are selected; otherwise all the dates are used. For each date that you select, the records in the Cust. Ledger Entry data item that are posted on that date are selected. The records for the Cust. Ledger Entry data item are grouped according to the value of the Document Type field, and the totals are maintained for the Amount field.

To design the sections

  1. Click View, and then click Sections to open Section Designer.

  2. Click Edit, click New, and then insert a Header section for the Date data item. This header will be used to contain the labels for the columns of data in the report.

  3. Insert two GroupFooter sections for the Cust. Ledger Entry data item. You create two GroupFooter sections for the Cust. Ledger Entry data item so that you can control their output separately. Both sections contain summarized information about the groups created by this data item.

  4. Insert a Footer section for the Cust. Ledger Entry data item. This section is used to display the subtotals.

  5. Insert a Footer section for the Date data item. This section is used to display the grand totals at the end of the report.

  6. Neither data item requires a Body section so you can delete them.

Expand image Adding Fields to the Report

The next step is to add the fields that you want to include in the various sections of the report.

To add fields to the report

  1. In Section Designer, select the Cust. Ledger Entry, GroupFooter (2) section, click View, and then click Field Menu to open the Field Menu window.

  2. In the Field Menu window, select the Posting Date, Document Type, and Amount fields.

  3. In Section Designer, click twice in the Cust. Ledger Entry, GroupFooter (2) section to add these fields.

  4. Move the labels into the Header section and align the fields.

  5. In Section Designer, select the Cust. Ledger Entry, GroupFooter (1) section, and then add the Document Type and Amount fields.

  6. Delete the labels for the fields that you have just added to the Cust. Ledger Entry, GroupFooter (1) section. These extra labels serve no purpose.

  7. Align the fields.

This report is not complete, you still need to add the fields that:

  • Contain the number of documents of each type that were posted on each date.

  • Calculate and display the total number of documents posted on each date.

  • Calculate and display the grand total number of documents posted in the period covered by the report.

  • Calculate and display the total amount posted on each date.

  • Calculate and display the grand total of the amount posted in the period that the report covers.

  • Display the date range that the user used to filter the information in the report.

To accomplish this, you need to write C/AL code in the triggers, define variables, and add the appropriate fields.

Expand image Creating a Global Variable with Code

The records in the Cust. Ledger Entry data item contain an amount and the total amount is calculated by using the properties of the data item in the report. You accomplished this in step 12 in the Using Virtual Tables as Data Model section, when you set the TotalFields property of the Cust. Ledger Entry data item to calculate a total based on the Amount field in the Cust. Ledger Entry table. This total is calculated separately for each date and is the basis for the grand total that you will calculate later. Unfortunately, the number of entries cannot be calculated in the same way because there is no field in the data item that contains this information. However, each record in the Cust. Ledger Entry table corresponds to exactly one entry, which means that the number of entries can be calculated by simply counting the records. To calculate the total number of entries made on each date.

To create a global variable with code

  1. Select the Cust. Ledger Entry data item in Report Designer, click View, and then click C/AL Code to open the C/AL Editor.

  2. Create a global variable called Qty and define its type as Decimal.

  3. Add the following C/AL code to these triggers in the Cust. Ledger Entry data item. To the Cust. Ledger Entry - OnPreDataItem() trigger, add the following line of code. CurrReport.CREATETOTALS(QTY);

  4. To the Cust. Ledger Entry - OnAfterGetRecord() trigger, add the following line of code. Qty :- 1;

The statement in the OnPreDataItem trigger maintains totals for the Qty variable in the same way that the TotalFields property specifies that totals are maintained for a field in a record. The statement in the OnAfterGetRecord trigger assigns a value of one to the Qty variable each time a record is retrieved.

You will use the CREATETOTALS function to maintain totals for each group and a grand total for the iteration of the data item loop. As data items are grouped according to the Document Type field, Qty contains the sum of all the entries of the same document type each time the Cust. Ledger Entry GroupFooter section is printed. When the Footer section is printed, Qty contains the sum of all the entries that were selected, that is, all the records that were entered on the same date.

The variable in the argument of the CREATETOTALS function must be of the Decimal data type because the function is usually used to add up amounts. This is why the Qty variable was declared as a Decimal rather than an Integer.

Expand image Adding Fields to the Report

You must now add some fields to the report that will display the totals calculated by the code in the previous section.

To add fields to the report

  1. Open Section Designer and open the Toolbox.

  2. Add a text box to the Cust. Ledger Entry, GroupFooter (1) section and open the Properties window of the text box.

  3. In the Value field of the SourceExpr property, click the AssistButton to open the C/AL Symbol Menu window.

  4. Select the Qty variable that you just defined.

  5. Add a label to the Header section, open the Properties window of the label, and in the Caption property, enter Qty. Be sure that the HorzAlign property is set to Right.

The Qty variable that you have just defined is a decimal. You must therefore change the formatting of the Qty text boxes in the sections so that they do not show any decimal places. The format of the Qty text boxes are defined as <2:2> by default when the SourceExpr is of the Decimal data type.

To change the formatting of the Qty text box

  1. Select the text box in Section Designer and open the Properties window.

  2. In the Value field of the DecimalPlaces property change the value to 0:0. The field will no longer display any decimals.

The next step is to add the field that will contain the total number of documents of each type that are entered on each date that is printed in the report.

To add the Qty field to the report

  1. Copy the Qty text box that you just added to the Cust. Ledger Entry, GroupFooter (1) section.

  2. Paste the text box into the Cust. Ledger Entry, GroupFooter (2) section. This text box will now display the total number of documents of each type entered on each date.

The report now contains fields that list the entries in the Cust. Ledger Entry table according to the date when they were entered and shows how many documents of each type were entered on that date.

Expand image Calculating the Total Number of Entries and Total Amount per Date

The next step in designing this report is to ensure that it displays some subtotals that show how many entries were made on each date, as well as the total amount entered on each date. This is why you created the Cust. Ledger Entry, Footer (3) section.

To calculate the subtotals

  1. Copy the Qty and Amount fields from the Cust. Ledger Entry, GroupFooter (2) section into the Cust. Ledger Entry, Footer (3) section.

    Note Note

    These fields will now display the total amount entered per date and the total number of documents entered on the date in question.

  2. Add a label to the Cust. Ledger Entry, Footer (3) section, open the Properties window of the label, and then in the Value field of the Caption property enter Total.

Expand image Print the Date in the First Iteration

In each iteration of the Date data item loop, you want to print the Date when the information selected from the Cust. Ledger Entry data item is entered. You could just use the body section of the Date data item and print the date there; the Period Start field of the data item, but this would mean that the date would print on a line by itself. Instead, the date should be printed along with the other information on the first line that comes from the Cust. Ledger Entry data item.

One solution is to use the Date field from the Cust. Ledger Entry data item. Unfortunately, if it is added to the GroupFooter section, the date will be printed on every line. This means that the finished report will not be very attractive and will be cluttered with redundant information.

A better solution is to define two GroupFooter sections for the Cust. Ledger Entry data item. One that includes the Date field and one that does not, and then control when they are output. This is why you created two GroupFooter sections earlier.

To add a date and control

  1. Create a global variable called IsDatePrinted and define its data type as Boolean.

  2. Add the following C/AL code to the OnPreDataItem trigger of the Cust. Ledger Entry data item: IsDatePrinted := FALSE;

    Note Note

    This code initializes the IsDatePrinted variable, with the value FALSE, before each iteration of the data item loop.

  3. Add the following C/AL code to the OnPreSection trigger of the Cust. Ledger Entry, GroupFooter (1) section of the Cust. Ledger Entry data item.

    CopyCode image Copy Code
    IF IsDatePrinted
THEN CurrReport.SHOWOUTPUT(TRUE)
ELSE CurrReport.SHOWOUTPUT(FALSE);

  4. Add the following C/AL code to the OnPreSection trigger of the Cust. Ledger Entry, GroupFooter (2) section.

    CopyCode image Copy Code
    IF IsDatePrinted
THEN CurrReport.SHOWOUTPUT(FALSE)
ELSE BEGIN CurrReport.SHOWOUTPUT(TRUE);
IsDatePrinted := TRUE;
END

These two pieces of code ensure that:

  • When a new iteration of the Cust. Ledger Entry data item begins, a date is not printed.

  • If the loop generates any output, only the second GroupFooter section containing the Date text box is included as output in the first iteration.

  • If additional output is generated, only the first GroupFooter section without the Date text box is printed.

Expand image Calculating the Grand Total Amount and the Grand Total Quantity

To complete this report you must ensure that it displays the total number of documents posted as well as the grand total of the amount posted in the period covered by the report. It should display this information at the end of the report in the Date Footer (2) section.

The next task is to calculate the grand total of all the amounts that are printed in the report. However, these amounts come from the Cust. Ledger Entry data item and not the Date data item. This means that you cannot use the TotalFields property of the Date data item to do the totaling.

To calculate grand totals

  1. Declare two global variables: GrandTotalAmount and GrandTotalQty of data type Decimal and Integer respectively.

  2. Add the following lines of code to the OnAfterGetRecord trigger of the Cust. Ledger Entry data item.

    CopyCode image Copy Code
    GrandTotalQty := GrandTotalQty + 1;
GrandTotalAmount := GrandTotalAmount + Amount;
    Note Note

    The first line adds one to the GrandTotalQty variable when a record is retrieved, while the second line adds the retrieved Amount to the GrandTotalAmount.

  3. Open Section Designer and add two text boxes to the Date, Footer (2) section.

  4. The first text box will be used to calculate the total number of documents in the report. Place it under the other Qty fields and open the Properties window of the text box.

  5. In the Value field of the SourceExpr property, click the AssistButton to open the C/AL Symbol Menu window.

  6. Select the GrandTotalQty variable that you just defined.

  7. The second text box will be used to calculate the grand total of the amounts displayed in the report. Place it under the other Amount fields and open the Properties window of the text box.

  8. In the Value field of the SourceExpr property, click the AssistButton to open the C/AL Symbol Menu window.

  9. Select the GrandTotalAmount variable that you just defined. This text box will now display the grand total of all the amounts in the report.

  10. Add a label to the Date, Footer (2) section and place it under the Total field in the Cust. Ledger Entry, Footer (3) section.

  11. Change the caption of this label to Total. The Date, Footer (2) section now contains the grand totals for the report.

Expand image Printing the Selected Range of Dates

The posting dates are used as a header in the left margin of the report, so the report would be complete if the final line could display the range of dates that the user selected before they ran the report.

To print the selected range of dates

  1. Create a variable called DateFilter and define its data type as Text, with a length of 100.

  2. Add the following C/AL code to the OnPreReport trigger of the report.

    CopyCode image Copy Code
    DateFilter := Date.GETFILTER("Period Start");

  3. Add a text box to the footer section of the Date data item, open the Properties window of the text box and enter DateFilter as its source expression.

    Note Note

    When the OnPreReport trigger is executed, the RequestForm has already been run. The GETFILTER function returns any filters on the field, which are passed as an argument, as a text string.

Expand image See Also

Tasks

Walkthrough: Designing a Simple Report
Walkthrough: Designing a More Advanced Report

Concepts

Designing Reports for the Classic Client


Walkthrough: Designing a Simple Report

Walkthrough: Designing a Simple Report

In this walkthrough, you will design a simple customer list report based on the Customer table. The report is designed in the Microsoft Dynamics NAV Classic client using Report Designer.

Expand image Prerequisites

  • To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

Expand image Defining the Data Model

The first step in creating this report is to define the data model on which the report is based. You define the data model by creating the data items.

To define the data model

  1. Click Tools, and then click Object Designer.

  2. In Object Designer, click Report, and then click New. The New Report window opens.

  3. In the Table field, click the AssistButton to select a table from the Table List window. For this example, select the Customer table.

  4. In the Report section, click Create a blank report, and then click OK. The Report Designer window opens.

  5. In the Data Item field, click the Assistbutton, and then select a table from the Table List window.

  6. Click View, and then click Properties to open the Properties window for the data item.

  7. Select the DataItemTableView property and in the Value field, click the AssistButton to open the Table View window.

  8. Select the Key, Order and Table Filter to use and then click OK. In this example, select the No. field as Key and set the sort order to Ascending. The Table Filter field is left empty, meaning that a permanent filter is not defined on the table.

  9. Select the ReqFilterFields property, and in the Value field, click the AssistButton to open the Field List window.

  10. Select the fields on which users will frequently need to set filters. In this example, select the No. and Country/Region Code fields, and then click OK.

  11. Click File, and click Save to save the report, and then run it from Object Designer to see the request form for this report.

Expand image Designing the Sections

Now that the data model is defined, you need to design the layout of the report. This is done using Section Designer.

To design the sections

  1. With Report Designer open, click View, and then click Sections to open Section Designer.In Section Designer, a section named "Customer.Body (1)" has been inserted. By default a Body section is inserted for each data item that has been created.

  2. Click Edit, and then click Insert New to insert a header section for the Customer data item. The Insert New Section window opens.

  3. Select Header as the Section Type and click OK.

  4. Click View, and then click Field Menu to open the field menu. Select the fields that you want in the report. Select multiple fields by holding down the CTRL key while selecting the fields.

  5. Move the cursor into the Body section of the data item. Click once to activate the window—the cursor changes into the Control Insertion cursor. Place the cursor on the left side of the section and click again. A text box with an attached label is inserted for each field that you selected.

  6. Click View, and then click Properties to open the Properties window. Click in the Header section to ensure that the Properties window displays the properties of the header. Note Look at the setting for SectionWidth (the unit of measure is 1/100 mm). The width of all the sections has been modified to make room for the controls that you inserted (the default width, when no controls have been inserted, is 12000). In this case, the resulting width is 15450, or 15.45 cm. This setting is fine if the report is going to be printed on A4 paper—A4 paper is 21 cm wide.

  7. Select all the labels in the Body section by holding down the CTRL key while clicking, and move them all into the Header section. This preserves the alignment of the labels and text boxes.

  8. Open the Properties window for the Header section and set the PrintOnEveryPage property to Yes. If the report consists of more than one page, the Header section will appear on every page.

  9. Resize the Body section by moving the cursor into Section Designer until it touches the lower bound of the Body section and turns into the vertical resizing cursor. Then click and drag the section upwards until it has the same height as the text boxes.

  10. Close and save the report and run it from Object Designer.

Expand image Aligning Labels

The label and the data in the No. column are not aligned because both controls have their alignment set to General, which is default. The label is left aligned because it contains text, while the text boxes are right aligned because they contain numbers.

To align labels

  1. With the report open in Report Designer, click View, and then click Sections to open Section Designer.

  2. Select the No. label and open the Properties window. Set the HorzAlign property to Right.

  3. Close and save the report.

  4. Run the report in Object Designer and click Preview.

Expand image Next Steps

Now you have created a simple customer list based on one table. The next step is to create a more advanced report. For more information, see Walkthrough: Designing a More Advanced Report.

Expand image See Also

Tasks

Walkthrough: Designing a More Advanced Report

Concepts

Designing Reports for the Classic Client
Designing Reports for the RoleTailored Client


Walkthrough: Designing a More Advanced Report

Walkthrough: Designing a More Advanced Report

The report designed in the Walkthrough: Designing a Simple Report was very simple: it was based on one table which it ran through and printed the records. In this walkthrough, you will learn how to design reports that are based on more than one table.

The sample report that you will create uses two tables: the Customer table and the Sales Line table, which contains not-yet-posted sales orders that contain information about the actual items that have been ordered by the customers. There is a one-to-many relationship between the two tables—while one customer can have many items on order, each sales line can only refer to one customer.

Expand image Prerequisites

  • To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

Expand image Defining the Data Model

In this section you will define the data model. The report must run through the Customer data item, and for each record in the Customer data item, select records in the Sales Line data item if the Sell-to Customer No. field has the same value as the No. field in the Customer data item. If there are no Sales Line records for a Customer, nothing is printed—not even the information from the Customer data item.

To define the data model

  1. From Microsoft Dynamics NAV, click Tools, and then click Object Designer.

  2. In Object Designer, click the Report button, click New, and then select Create a blank report.

  3. In the Report Designer window, select the Customer table as the first data item, and the Sales Line table as the second data item.

  4. Select the Sales Line data item and click the right-arrow button once to indent it.

  5. Open the Properties window (SHIFT+F4) for the Sales Line data item.

  6. Set the DataItemLinkReference property to Customer. In most cases, including this one, this is the default.

  7. In the Value field of the DataItemLink property, click the AssistButton to open the DataItem Link window.

  8. In the Field field, enter the name of the field from Sales Line table that must correspond to a field from the Customer table. Use the lookup function to select the field. For this example, select the Sell-to Customer No. field.

  9. In the Reference Field field, enter the name of the field from the Customer table that must correspond to the field from the Sales Line table. Again, use the lookup function to select the field. In this example, select the No. field from the Customer table.

  10. Finally, open the Properties window for the Customer data item, and set the PrintOnlyIfDetail property to Yes. This means that the Customer body sections are only printed if there is data to print from the Sales Line table.

Expand image Designing the Sections

Because you already know how to design the sections for a report with one data item, the following procedure shows how to design sections that involve two data items.

To design the sections

  1. Open Section Designer, click Edit, click Insert new, and then add a Header section for the Customer data item.

  2. Click View, and then click Field Menu to open the Field Menu window.

  3. Add the No., Name, Address, and Phone No. fields to the Customer, Body (2) section. Move the labels up into the Header section.

  4. Open the Field Menu window and add the Document No., Shipment Date, Description, Quantity, Unit Price, and Amount fields to the Sales Line, Body (1) section.

  5. Move the labels into the header section of the Customer data item.

  6. Set the PrintOnEveryPage property of the Customer, Header (1) section to Yes. Now the labels for both the Customer records and the Sales Line records will be printed as column captions in the Customer, Header (1) section.

  7. Change the labels for the Sales Line columns to normal font weight instead of the default bold to make the connection between labels and data clear.

  8. Change the text boxes of the Customer data item to bold, to make these records stand out among the lines that are printed.

  9. Resize the Sales Line labels to occupy only one line, and add an empty line to the header section.

  10. Save and close the report, and run it from Object Designer.

Expand image See Also

Tasks

Walkthrough: Designing a Simple Report

Concepts

Designing Reports for the Classic Client
Designing Reports for the RoleTailored Client


Walkthrough: Designing a Report with Grouping and Totaling

Walkthrough: Designing a Report with Grouping and Totaling

In this walkthrough, you will learn how design a report with grouping and totaling. How you group and total data is a crucial element of creating useful reports. By grouping and totaling data, your reports can contain information that is not otherwise readily available. You can use grouping and totaling to enhance reports in several ways.

Expand image Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

  • To complete Walkthrough: Designing a More Advanced Report.

Expand image Defining the Data Model

First, you will define the data model for the report. For each record in the Customer data item, the records in the Sales Line data item that are related to this customer are selected. Records from the Sales Line data item are grouped according to the item number and totals are maintained for the Quantity and Amount fields of the Sales Line data item.

To define the data model

  1. In the Classic client, open Object Designer.

  2. Under Reports, locate the report that you created in the Walkthrough: Designing a More Advanced Report and click the Design button.

  3. Open the Properties window for the Sales Line data item.

  4. In the Value field of the GroupTotalFields property, enter the name of the field that you want to use to group the records. You can use the AssistButton to select the field. In this example, use the No. field.

  5. In the Value field of the DataItemTableView property, use the AssistButton to select a key. You must select a key that contains the field that you want to group by.

    Note Note

    If the key you select is a composite key, the grouping can fail if there are other fields in the key before the grouping field, and the contents of one of these field changes. You may have to create a distinct key for reports that access data in ways other than those used by your application.

  6. In the Value field of the TotalFields property, enter the names of the fields for which totals should be calculated. Use the AssistButton to select the fields. In this example, select the Quantity and Amount fields.

Expand image Designing the Header and Body Sections

Now that the data model is in place, there is a hierarchy of data items, where Customer is the data item at the highest level and Sales Line is an indented data item. The Sales Line records are grouped on the No. field, and totals are calculated for the Amount and Quantity fields. Until now, only the Header and Body sections have been used. To print totals, you will need to use some new sections, for more information, see Types of Report Sections.

To design the header and body sections

  1. In Report Designer, open the report that you are working on.

  2. Click View, and then click Sections. When you open Section Designer, a body section for each data item has been inserted.

  3. Select the Customer data item, click Edit, and then click New to open the Insert New Section window.

  4. Add a Header section. This section will be used to print headings for the columns in the report.

  5. Select the Sales Line data item

  6. Click Edit, click New, and then add a GroupFooter section. This section will be used to print the summary information about each item.

  7. Click Edit, click New, and then add a Footer section for the Sales Line data item. This section will be used to print the summary information about each customer.

  8. Select the section for the Body section of the Sales Line data item. Click Edit, and then click Delete.

    Note Note

    You need to delete this section because nothing will be printed in the Body section of the Sales Line data item.

  9. You are prompted to confirm that you want to delete the section.

  10. Select the labels for the Sales Line that you added to the Customer Header earlier and delete them.

  11. Adjust the vertical size of the labels.

Expand image Designing the Footer Sections

Now you need to design the Footer sections and ensure that they display the information that you want.

To design the footer sections

  1. Select the GroupFooter section of the Sales Line data item by clicking the section bar. Click View, and then click Field Menu to open the Field Menu window.

  2. In the Field Menu window, select the No., Description, Quantity, and Amount fields.

  3. Click twice in the GroupFooter section of the Sales Line data item to insert these fields. Delete the labels, and resize the section vertically.

  4. Select the Footer section of the Sales Line data item.

  5. In the Field Menu window, select the Amount field and insert it in the footer section directly below the Amount field in the GroupFooter section. Select the label and delete it. Keep the default size for the section so there is empty space before each new customer.

  6. Select the No. label in the Customer Header. Open the Properties window and set the value of the HorzAlign property to Right.

  7. Save, close, and run the report.

Expand image See Also

Tasks

Walkthrough: Creating a Nonprinting Report
Walkthrough: Creating a Simple Document
Walkthrough: Creating Advanced Sample Reports
Walkthrough: Designing a Simple Report


Redesigning Classic Reports with Visual Studio Report Designer

Redesigning Classic Reports with Visual Studio Report Designer

The following table provides an overview of how to locate Microsoft Dynamics NAV 2009 information about redesigning Classic report layouts as client report definition (RDLC) layouts.

To | See
View and design Classic report layouts and RDLC report layouts | Understanding Report Redesign
Create an RDLC report layout for an existing report | How to: Create a Layout Suggestion
Create a new RDLC report layout | Designing Reports for the RoleTailored Client
Manually modify a new RDLC report layout | Manual Updates to Redesigned RDLC Report Layouts
Work with both Classic client Report Designer and Visual Studio Report Designer | How to: Integrate Classic Client Report Designer and Visual Studio Report Designer
Learn how to redesign report layouts from the standard application | Walkthrough: Redesigning a Customer List Report and Walkthrough: Redesigning a Customer - Order Summary Report


Understanding Report Redesign

Understanding Report Redesign

In Microsoft Dynamics NAV 2009, there are two different layouts for reports:

  • Classic report layouts

  • Client report definition (RDLC) report layouts

The following table shows how you view and design each type of report.

Task | Classic report layout | RDLC report layout
View from Classic client. | Yes | No
View from RoleTailored client. | Yes | Yes
Design by using only Classic client Report Designer. | Yes | No
Design by using Classic client Report Designer and Visual Studio Report Designer. | No | Yes

To create a new RDLC layout for your existing reports, you must use Report Designer in the Classic client and Visual Studio Report Designer. You use the Create Layout Suggestion function in the Classic client to create an initial RDLC suggestion, and then you can manually modify the layout.

To view the Classic report layout of your existing reports from the RoleTailored client, you must delete the RDLC layout. If you run a report from the RoleTailored client, then the Classic report layout will be shown. For more information, see How to: View Classic Report Layouts from the RoleTailored Client

New Features in Visual Studio Reports

The following features are available in Visual Studio Report Designer but not in Classic reports:

  • Interactive reporting

    • Hide data

    • Toggle details on or off

    • Sort data

    • Filter data

  • Graphical capabilities

    • Multiple options for charts

    • Images

  • Advanced editing, such as the ability to change the font on multiple fields at one time

  • Ability to export to PDF and Microsoft Office Excel files

For more information about how to design an RDLC layout with these features, see Defining a Report Layout (Visual Studio Report Designer). We recommend that you become familiar with the Defining a Report Layout topic and subtopics so that you know the capabilities of RDLC report layouts and can take advantage of them in your Microsoft Dynamics NAV 2009 reports. All report layout design tasks that are described in the Defining a Report Layout section apply to Microsoft Dynamics NAV 2009 reports with the following exceptions:

  • You cannot reference a Microsoft Dynamics NAV report in a subreport.

  • If you create drillthrough reports, then you use Jump to URL instead of Jump to Report to link from a report to another report. For more information, see Walkthrough: Creating a Link from a Report to a Report.

Redesigning Classic Report Layouts as RDLC Report Layouts

If you want to redesign your existing reports to take advantage of the features in Visual Studio Report Designer, then you should use the following steps:

  1. Analyze the report to determine what it needs to display, what is supported in the new report, and if you need to make modifications.

  2. Create a layout suggestion.

  3. Manually update the new report.

  4. Transform the request form.

Analyze the Report

Before you manually update the new RDLC report layout, you should understand the purpose of the report. Sometimes you can achieve the same result by using different functionality in the RDLC report layout than in the Classic report layout. If you understand the purpose of the report and the features that are available in Visual Studio Report Designer, then you can determine what manual modifications you need to make to the new RDLC report layout.

In addition to understanding the Visual Studio Report Designer features that you can use in RDLC report layouts, you should also understand how the dataset, which contains the data that is displayed in the report, is generated. For a Classic report layout, the data for each data item is retrieved from the data item and is formatted in the report sequentially. For example, if you run an Order Confirmation report for multiple sales orders and the data for the first order is retrieved and formatted for the Classic report layout, then the data for the second order is retrieved and formatted, and so on. For an RDLC report layout, all data for the report is retrieved from the data item into one dataset, and then the data is placed in the RDLC layout. For example, if you run an Order Confirmation report for multiple orders, then the data from all orders is merged into one dataset. The layout specifies that the data is grouped on pages according to the sales order number.

Create a Layout Suggestion

The function to create a layout suggestion is included on the Tools menu in the Classic client. For more information, see How to: Create a Layout Suggestion.

Manually Update the Layout Suggestion

After you create a layout suggestion, the RDLC report layout may not display what you want, and you must perform some manual updates. For example, you may need to redesign headers and footers, verify that decimal and date fields are formatted correctly, or modify how blank lines are specified.

For more information about these examples and about other manual modifications to make after you create a layout suggestion, see Manual Updates to Redesigned RDLC Report Layouts.

Transform the Request Form

If your report has a request form that contains options, then you must transform that form. This is a separate step from creating a new report layout. You use the form transformation tool to transform request forms. For more information, see How to: Transform the Request Form.

If your report has a request form that does not contain options, the request form will be transformed automatically.

Viewing Classic Reports from the RoleTailored Client

From the RoleTailored client, you can either view the RDLC report layout or the Classic report layout. To view the Classic report layout from the RoleTailored client, you must have the Classic client installed, and you must ensure that an RDLC layout for the report does not exist. If you have already created a layout suggestion for a report, then you must delete that layout suggestion. For more information, see How to: View Classic Report Layouts from the RoleTailored Client.

See Also

Concepts

Understanding Headers and Footers


How to: View Classic Report Layouts from the RoleTailored Client

How to: View Classic Report Layouts from the RoleTailored Client
See Also

In Microsoft Dynamics NAV, there are two different layouts for reports:

  • Classic report layouts

  • Client report definition (RDLC) report layouts

To view the Classic report layout of a report from the RoleTailored client, you must ensure that the RDLC layout does not exist. If the RDLC layout does not exist and if you run a report from the RoleTailored client, then the Classic report layout is shown.

Before you begin this procedure, confirm the following:

  • The report for which you are deleting the RDLC layout does not have any global variables or global functions. If a report has global variables or global functions and you delete the transformation layout, you will get the following error when you run the report from the RoleTailored client:

    Report state information cannot be transferred to Classic client report from the RoleTailored client. One or more of the public functions on report <report number> has been called prior to running the report.

    You must either redesign the report so that it does not use global variables or global functions, or create an RDLC report layout for the report so that you can view the RoleTailored report from the RoleTailored client.

  • You have installed the Classic client, so that you can view the Classic report layout. You must have the same version of the Classic client and the RoleTailored client installed.

  • TCP/IP is enabled on your SQL Server. To enable TCP/IP, do the following:

    1. Click the Start button, point to All Programs, point to Microsoft SQL Server 2005 or Microsoft SQL Server 2008, point to Configuration Tools, and then click SQL Server Configuration Manager.

    2. In SQL Server Configuration Manager, expand SQL Server Network Configuration, click Protocols for MSSQLSERVER, right click TCP/IP, and then click Enable.

  • You are aware of the differences in supported report functions and properties for RDLC and Classic report layouts. For more information, see Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client.

To view a Classic report layout from the RoleTailored client

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report for which you want to delete the RDLC layout, and then click Design.

  3. On the Tools menu, click Delete Layout. In the dialog box, click Yes to confirm that you want to delete the layout.

  4. Close Report Designer.

  5. In the RoleTailored client, run the report. For more information about running a report from a command prompt, see How to: Use a Shortcut to Run a Report.

See Also

Concepts

Understanding Report Redesign
Developing Applications for the Classic Client and RoleTailored Client


Understanding Headers and Footers

Understanding Headers and Footers

Headers and footers in client report definition (RDLC) report layouts have the following limitations:

  • Expressions in a header or footer can refer to only one report item.

  • Data-bound fields in a header or footer will give an error. You must put the data-bound field in a text box in the body section, and either save the data to a global variable, or use ReportItem!<text box name>.

  • You can have only one report header, one body, and one report footer in a report.

    Note Note

    You can have group headers and footers and table headers and footers.

When you create a layout suggestion, data-bound fields in the header are automatically moved to hidden fields in the body of the report. However, in some cases, you may need to create additional hidden text boxes in the body section of a report so that in the new layout, you can reference that report item in the header or footer.

The following topics describe modifications that require creating new hidden text boxes so that the data can be used in a header or footer:

  • How to: Hide Nonfiltered Headers

  • How to: Redesign the Number of Copies Option

  • How to: Print Header Information on Multiple Pages

For more information about Visual Studio report layouts, see Defining a Report Layout.

See Also

Tasks

How to: Redesign Footers


How to: Create a Layout Suggestion

How to: Create a Layout Suggestion

When you create a layout suggestion for a report, a new client report definition (RDLC) report layout is created. You must complete additional checks and manual modifications to this suggested layout before you view the RDLC layout from the RoleTailored client.

Use the following procedure to create the suggested RDLC layout.

Before you begin this procedure, confirm the following:

  • You have Microsoft Dynamics NAV 2009 installed with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements are met. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements in Microsoft Dynamics NAV 2009 Installation and Configuration Help.

  • You have basic knowledge of Visual Studio Report Designer. For more information, see Report Designer (Visual Studio).

To create the suggested layout

  1. In the Classic client, click Tools, and then click Object Designer.

  2. In Object Designer, click Report, select a report, and then click Design.

  3. In the Tools menu, select Create Layout Suggestion. A suggestion for an RDLC report layout is created.

    Note Note

    If you have already created a layout suggestion or have edited this report layout in Visual Studio, this step will overwrite the layout that you previously created or edited. If you want to edit the existing layout, in the View menu, select Layout.


How to: Integrate Classic Client Report Designer and Visual Studio Report Designer

How to: Integrate Classic Client Report Designer and Visual Studio Report Designer
See Also

To create and modify client report definition (RDLC) report layouts, you must use Visual Studio. When you create an RDLC layout for a report, you may need to perform some steps in the Classic client Object Designer and some steps in Visual Studio Report Designer. To work with both Object Designer and Visual Studio Report Designer, you need to know when and where to save your work and how to switch between them efficiently.

You can save the RDLC report layout of the report in Visual Studio multiple times while you make changes. However, after you save those changes in the Classic client, if you make additional changes in Visual Studio, then those changes are not saved in the Classic client. After you save the report in the Classic client, we recommend that you close the report in Visual Studio so that you do not make additional changes that will not be saved. If you want to change the layout after saving the report in the Classic client, then you must click the View menu in the Classic client and then click Layout to reopen the RDLC layout in Visual Studio.

To work with both Object Designer and Visual Studio Report Designer

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. To modify a Classic client report layout, in Object Designer, click Report, select the report that you want to modify, and then click Design.

  3. To create a new RDLC report layout for a report, in Object Designer, click Report, select the report, and then click Design. On the Tools menu, click Create Layout Suggestion.

  4. To modify an existing RDLC report layout, in Object Designer, click Report, select the report that you want to modify, and then click Design. On the View menu, click Layout.

  5. After you make changes in the RDLC layout, on the File menu, click Save Report.rdlc.

  6. In the Classic client, select an empty line in the report in Object Designer. A dialog box appears the following message:

    The layout of report id: ' <report ID> ' is changed by another application.

    Filename of the changed RDLC: <filename>

    Do you want to load the changes?

  7. In the dialog box, click Yes to load the changes that you made to the RDLC layout into the Classic client.

  8. In the Classic client, on the File menu, click Save.

  9. In the Save dialog box, select Compiled, and then click OK.

    Note Note

    If you close the report in Object Designer in the Classic client, make changes in Visual Studio Report Designer, and try to save the RDLC layout, then you will get the Save As dialog box. This is because the RDLC layout that you are trying to save is not connected to Object Designer. When you closed the report in Object Designer, the version of the RDLC layout that was connected to Object Designer was saved in the report and then deleted.

  10. (optional) To make additional changes to the report layout, on the View menu, click Layout, and then repeat steps 5 through 9.

See Also

Tasks

Troubleshooting: Classic Client Report Designer and Visual Studio Report Designer


Manual Updates to Redesigned RDLC Report Layouts

Manual Updates to Redesigned RDLC Report Layouts

After you create a client report definition (RDLC) report layout for a report, the layout may require manual modifications so that it displays what you want. The topics in the following table describe the manual steps that you must perform.

Topic | Applies to all reports | Applies to specific reports
How to: Add and Identify Hidden Fields | Yes | No
How to: Add BlankNumbers and BlankZero Functions | No | Reports that do not use BlankNumber and BlankZero properties at the time that you create a layout suggestion but to which you want to add blank zero and blank number functionality.
How to: Apply Conditional Visibility Controls | No | Reports that have sections that are displayed conditionally.
How to: Change a Row to Bold Font | No | Reports that display some data in bold font, based on the value of the data.
How to: Change the Printed Values of Boolean Variables | No | Reports that have printed values of Boolean variables.
How to: Create New Pages per Record | No | Reports that have a new page for each record.
How to: Format Date Values | No | Reports that display dates.
How to: Format Decimal Values | No | Reports that display decimal numbers.
How to: Hide Nonfiltered Headers | No | Reports that have a filter option and a filter header line and in which the user can choose not to specify a filter.
How to: Resolve Formatting Issues Caused by Hidden Fields | Yes | No
How to: Print Header Information on Multiple Pages | No | Reports with multiple tables and multiple pages on which you want to print header information on each page.
How to: Redesign Blank Lines | No | Reports that display blank lines between data.
How to: Redesign SourceExpr Values in Conditionally Visible Sections | No | Reports that execute code based on whether a section is visible.
How to: Redesign Footers | No | Reports that have footers.
How to: Redesign the Number of Copies Option | No | Reports that have an option for number of copies.
How to: Redesign Option Strings in Multilanguage Implementations | No | Reports that use option strings in a multilanguage implementation.
How to: Redesign Section Triggers that Calculate Percentage | No | Reports that have section triggers that calculate percentage.
How to: Reset Page Numbers | No | Reports that have grouped data and page numbers that are reset after each group.
How to: Specify Rounding Precision | No | Reports that have rounding to a value other than the nearest integer.
How to: Verify Code on a Report | Yes | No
How to: Verify Controls on a Report | Yes | No
How to: Verify Page Headers and Table Headers | Yes | No
How to: Verify the Paper Size | Yes | No
How to: Verify TrueType Fonts | Yes | No


How to: Add and Identify Hidden Fields

How to: Add and Identify Hidden Fields

If you have hidden fields on a report, we recommend that you mark them so that they are easy to identify. After you create a client report definition (RDLC) layout for a report, you may need to move hidden fields to a different location in the layout to avoid problems with formatting.

For example, you can use hidden fields if you need to reference a data-bound field from the header of a report. For more information, see Understanding Headers and Footers.

You can also use hidden fields if you have an option on a request form, such as whether to show values in the local currency (LCY).

To add and identify a hidden field

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report to which you want to add a hidden field, and then click Design.

  3. On the View menu, click Sections.

  4. To create a new hidden field, on the View menu, click Toolbox, and then click Text Box. In Section Designer, add a text box.

  5. Select the text box that you created in step 4 or select an existing hidden field. On the View menu, click Properties.

  6. If this is a new hidden field and you want to use the value of a field elsewhere in the report, in the Properties window, then specify the value in the SourceExpr field.

  7. In the ForeColor field, enter 65535 to specify that the color in Section Designer is yellow.

  8. In the Visible field, select No from the drop-down list.

  9. In the Width field, specify a small width, such as 150.

  10. On the File menu, click Save.

  11. In the Save window, select the Compiled check box, and then click OK.

See Also

Tasks

How to: Resolve Formatting Issues Caused by Hidden Fields

Concepts

Understanding Headers and Footers
Designing Reports for the RoleTailored Client
Understanding Report Redesign


How to: Add BlankNumbers and BlankZero Functions

How to: Add BlankNumbers and BlankZero Functions
See Also Example

In the Classic client, you can use the BlankNumbers and BlankZero functions for formatting.

  • The BlankNumbers function determines whether a range of numbers will be set to blank.

  • The BlankZero function determines whether a field appears blank if the value is 0 (zero) or true.

In the RoleTailored client, the BlankNumbers and BlankZero functions do not exist by default. If you create a client report definition (RDLC) report layout for a report in which BlankNumbers or BlankZero are used in the Classic layout, then the new report layout includes the following functions and you do not need to modify the layout:

  • BlankZero

  • BlankPos

  • BlankNeg

  • BlankZeroAndPos

  • BlankNegAndZero

If you create an RDLC report layout for a report in which the BlankNumbers or BlankZero functions are not used in the Classic report layout, then you do not get these functions in the new RDLC report layout. If you want to modify the report to include this functionality, then you may need to add these functions.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To add BlankNumbers and BlankZero functions

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report in the standard application that contains the BlankNumbers and BlankZero functions, and then click Design. For example, report 206, Sales - Invoice, contains the BlankNumbers and BlankZero functions.

  3. On the View menu, click Layout.

  4. In Visual Studio, in the Report.rdlc file, click the Report menu, and then click Report Properties.

  5. In the Report Properties window, select the Code tab.

  6. Copy the code on the Code tab for the following functions:

    • BlankZero

    • BlankPos

    • BlankNeg

    • BlankZeroAndPos

    • BlankNegAndZero

  7. In Object Designer, select the report to which you want to add the functions, and then click Design.

  8. On the View menu, click Layout.

  9. In Visual Studio, in the Report.rdlc file for the report to which you want to add the functions, click the Report menu, and then click Report Properties.

  10. In the Report Properties window, select the Code tab.

  11. Paste the functions into the Custom code text box, and then click OK.

  12. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

Example

The following code shows the BlankZero, BlankPos, BlankNeg, BlankZeroAndPos and BlankNegAndZero functions in an RDLC report layout.
Visual Basic CopyCode image Copy Code
Public Function BlankZero(ByVal Value As Decimal)
    If Value = 0 Then
        Return ""
    End If
    Return Value
End Function

Public Function BlankPos(ByVal Value As Decimal)
    If Value > 0 Then
        Return ""
    End If
    Return Value
End Function

Public Function BlankZeroAndPos(ByVal Value As Decimal)
    If Value >= 0 Then
        Return ""
    End If
    Return Value
End Function

Public Function BlankNeg(ByVal Value As Decimal)
    If Value < 0 Then
        Return ""
    End If
    Return Value
End Function

Public Function BlankNegAndZero(ByVal Value As Decimal)
    If Value <= 0 Then
        Return ""
    End If
    Return Value
End Function

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Apply Conditional Visibility Controls

How to: Apply Conditional Visibility Controls

Some reports have sections that are printed conditionally. For example, if the request form for the report has a Show Address Details check box, then the address details are printed only if the check box is selected. As another example, a report could show data based on a value such as a balance. If the balance is 0, then the report does not show the balance. In the Classic report layout, you can use section triggers to specify the conditions for showing the data. In a client report definition (RDLC) report layout, section triggers are not supported. To specify conditional visibility in an RDLC report layout, use an expression on the Visibility property of the control or table row.

For an example of applying conditional visibility controls to hide nonfiltered headers, see How to: Hide Nonfiltered Headers.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To transform conditional visibility controls

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Visual Studio, in the Report.rdlc file, select the control or table row that you want to show conditionally.

  5. On the View menu, click Properties Window.

  6. In the Properties window, expand Visibility.

  7. Under Visibility, in the Hidden field, select <Expression…> from the drop-down list.

  8. In the Edit Expression window, enter the conditional statement for when the control or row is hidden, and then click OK.

    The following illustration shows an example of a conditional visibility expression on report 2, General Journal - Test, in the standard application.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Change a Row to Bold Font

How to: Change a Row to Bold Font

In some reports, you may want to format rows as bold based on the value of a field in the row. For example, in the standard application, the Classic client report 1, Chart of Accounts, rows whose account type is Posting are bold, while rows whose account type is anything other than Posting are not bold.

In the Classic client layout of a report, to specify that some rows are bold, you can create two sections, each with the same fields for the rows of the table. In one section, the rows are bold, and in the other section, the rows are not bold. Then, you can create an OnPreSection section trigger on each section that has a conditional statement. The section trigger for the section in which the rows are bold only calls the SHOWOUTPUT function if the account type is Posting. The section trigger for the section in which the rows are not bold only calls the SHOWOUTPUT function if the account type is not Posting.

In the client report definition (RDLC) layout of a report, section triggers are not supported so you must redesign how you specify that some rows are bold.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To conditionally change rows to bold font

  1. Add a hidden field to the body section of the Classic report layout. The hidden field should contain the field on which you will determine whether the row is bold. For example, in the Chart of Accounts report, the hidden field contains the account type field. For more information, see How to: Add and Identify Hidden Fields.

  2. In Object Designer, click Report, select the report that you are modifying, and then click Design. In the Classic client, click the View menu, and then click Layout.

  3. In Microsoft Visual Studio, in the Report.rdlc file, select the hidden field that you created in step 1.

  4. In the View menu, click Properties Window.

  5. In the Properties window, under the Visibility field, set Hidden to True.

  6. In the Report.rdlc file, select the data row that you want to display as bold.

  7. In the Properties window, expand the Font field. In the FontWeight field, select <Expression…> from the drop-down list.

  8. In the Edit Expression window, select Fields(DataSet_Result) from the list. Under Field, double-click the field on which you will determine whether the row is bold.

  9. In the text box at the top of the Edit Expression window, use the field that you selected in step 8 to create a conditional statement. For example, the following is the conditional statement for report 1.

    =IIf(Fields!G_L_Account___Account_Type_.Value="1","Normal","Bold")

  10. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Change the Printed Values of Boolean Variables

How to: Change the Printed Values of Boolean Variables

In a Classic client report layout, when a Boolean value appears on a report, the value is printed as "yes" or "no" in the target language. In a client report definition (RDLC) report layout, when a Boolean value appears on a report, the value is printed as "true" or "false" in the target language.

In some cases, you may want to change the printed value of a Boolean variable in an RDLC report layout to "yes" or "no" instead of "true" or "false." For example, you may want RDLC report layouts to use the same wording as the reports that you designed in a previous version of Microsoft Dynamics NAV. You may also have Classic and RDLC report layouts and require the same wording in both layouts.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To change the printed value of a Boolean variable

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report for which you want to change the printed values of Boolean variables, and then click Design.

  3. On the View menu, click Sections.

  4. Right-click the text box that displays a Boolean variable, and then click Properties.

  5. In the Properties window, in the SourceExpr field, change the BooleanVariable to FORMAT(BooleanVariable).

  6. In the Properties window, in the Caption field, enter the value for the caption of the variable.

  7. On the File menu, click Save.

  8. In the Save window, select the Compiled check box, and then click OK.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Create New Pages per Record

How to: Create New Pages per Record

For some reports, you may want to print a new page for each new record. In a Classic report layout, you use either the NewPagePerRecord property or the CurrReport.NEWPAGE property. In a client report definition (RDLC) report layout, the NewPagePerRecord property and the CurrReport.NEWPAGE property are not supported. To print a new page for each record in an RDLC report layout, you must do one of the following:

  • If you used the CurrReport.NEWPAGE property, then add a new page number variable that you increment each time you used CurrReport.NEWPAGE. Group data based on the new page number variable and add a page break at the end of each group.

  • Group data in the report based on where you want to start a new page and add a page break at the end of each group

An example of a report that begins a new page for each new record is report 25, Account Schedule, in the standard application.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To create a new page number variable to replace the CurrReport.NEWPAGE property

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, select Report, select the report in which you use the CurrReport.NEWPAGE property, and then click Design.

  3. On the View menu, click C/AL Globals.

  4. In the C/AL Globals window, on the Variables tab, add the following variables.

    Name DataType

    PageGroupNo

    Integer

    NextPageGroupNo

    Integer

  5. On the View menu, click C/AL Code.

  6. In the C/AL Editor, add the following code to the OnPreDataItem trigger to create and initialize the new page number variable.

    CopyCode image Copy Code
    IF ISSERVICETIER THEN BEGIN
   PageGroupNo := 1;
   NextPageGroupNo := 1;
END

  7. For each place in the code where you call the CurrReport.NEWPAGE property in the Classic client, add code to increment the PageGroupNo variable, as shown in the following example.

    CopyCode image Copy Code
    IF ISSERVICETIER THEN BEGIN
   PageGroupNo += 1;
END;
    Note Note

    You cannot add the line of code to section triggers. If you use the CurrReport.NEWPAGE property in a section trigger, then you must add the line of code to increment the PageGroupNo variable to a DataItem trigger instead.

  8. On the View menu, click Sections.

  9. Add a text box where the SourceExpr value is PageGroupNo. Add another text box where the SourceExpr value is NextPageGroupNo. Set both text boxes to be hidden. For more information, see How to: Add and Identify Hidden Fields.

  10. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

To create a new page per record by grouping data

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report that you want to modify to print a new page per record, and then click Design.

  3. If you performed the steps in the preceding procedure to create a new page number variable, or if the field on which you want to group already exists in a text box in the layout, then go directly to step 9. If you need to add the field on which you want to group to the layout, you must complete steps 4 through 8.

  4. On the View menu, click Sections.

  5. In Section Designer, create a text box for the field on which you want to group. Typically, you should create this text box in the body section where the record that you want to group by is placed.

  6. Right-click the text box that you created in step 4, and on the shortcut menu, click Properties.

  7. In the TextBox Properties window, set the Visible property to No.

  8. Close Section Designer.

  9. On the View menu, click Layout.

  10. In Microsoft Visual Studio, in the Report.rdlc file, select the text box for the field on which you want to group.

  11. On the View menu, click Properties Window.

  12. In the Properties window, under Visibility, set Hidden to True.

  13. In the table data region of the layout, right-click the data row that you want to group, and then click Insert Group.

  14. In the Grouping and Sorting Properties window, under Group on, select a line to add an expression. From the drop-down list, select the field on which you want to group.

  15. Clear the Include group footer check box.

  16. Select the Page break at end check box, and then click OK.

  17. Select the data row to which you added the grouping.

  18. In the Properties window, under Visibility, set Hidden to True.

  19. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Format Date Values

How to: Format Date Values

When you create a client report definition (RDLC) layout for a report, you must modify date values so that they are formatted correctly. Use the following procedure to verify or change the format of a date.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To format date values

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click Sections.

  4. Right-click the text box that displays a date, and then click Properties.

  5. In the Properties window, in the SourceExpr field, change the date value to FORMAT(<date value>).

  6. In the Properties window, in the Caption field, enter the value for the caption of the variable.

  7. On the File menu, click Save.

  8. In the Save window, select the Compiled check box, and then click OK.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Format Decimal Values

How to: Format Decimal Values

When you create a client report definition (RDLC) layout for a report, a format variable is created for each decimal variable. The format information from the Classic client report layout is stored in the format variable. Decimal values that exist on the Classic report layout will be formatted in the RDLC layout by using the format variable. If you create new controls that use decimal values in an RDLC report layout, then you must manually specify to use the format variable instead of the original decimal variable to get the formatted decimal variable.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To format decimal values

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Visual Studio, in the report.rdlc file, right-click the text box that displays a decimal value, and then click Properties.

  5. In the Properties window, click the Format tab.

  6. In the Format code field, verify that the variable used is the variable with _Format appended to the name. For example, if the Value field on the General tab is =Fields!CustSalesLCY_2_.Value, then the Format code field on the Format tab should be =Fields!CustSalesLCY_2_Format.Value.

  7. If the variable used is not the variable with _Format appended to the name, then you must change the variable. To change the variable, do the following steps:

    1. To select the format variable from a list, click the ellipsis button (…) next to the Format code field.

    2. In the Choose Format window, click the function button (fx) next to the Custom field.

    3. In the Edit Expression window, select Fields (DataSet_Result), select the variable from the list, and then click OK.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Hide Nonfiltered Headers

How to: Hide Nonfiltered Headers

If you apply a filter to the data in a report, then there is an additional header row in the report to display the filter. In the Classic client report layout, if the user does not specify a filter, the filter information is not displayed in the report. When you create a client report definition (RDLC) report layout, you must make some modifications so that if no filter is specified, then the filter information is not displayed.

First, in the Classic report layout, you must add a hidden control to the section for the filter variable. You must add this control so that the filter variable is included in the dataset in the RDLC report layout. Next, in the RDLC report layout, you must create a conditional expression that uses the filter variable that you added to the Classic report layout to hide the filter information.

An example of a report with an additional header row to display filter information is report 113, Customer/Item Sales. The following illustration shows the two hidden fields that were added to report 113 for the two filter variables, CustFilter and ItemLedgEntryFilter.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To hide non-filtered headers

  1. Add a hidden field to the body section of the report for each filter variable. For example, in report 113, Customer/Item Sales, create two hidden fields:

    • A field where SourceExpr is CustFilter.

    • A field where SourceExpr is ItemLedgEntryFilter.

    For more information, see How to: Add and Identify Hidden Fields.

  2. In the Classic client, on the Tools menu, click Object Designer.

  3. In Object Designer, click Report, select the report that you want to modify, and then click Design.

  4. On the View menu, click Layout.

  5. In Microsoft Visual Studio, in the Report.rdlc file, select the row that displays the filter header.

  6. On the View menu, click Properties Window.

  7. In the Properties window, expand the Visibility field. In the Hidden field, select <Expression…> from the drop-down list.

  8. In the Edit Expression window, create a conditional statement. For example, the following are the conditional statements for report 113.

    CopyCode image Copy Code
    =IIF(First(Fields!CustFilter.Value) = "",TRUE,FALSE)
IIF(First(Fields!ItemLedgEntryFilter.Value) = "",TRUE,FALSE)

  9. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Print Header Information on Multiple Pages

How to: Print Header Information on Multiple Pages

To successfully create a client report definition (RDLC) report layout, you may need to add hidden fields to the body of the report. Typically, you add hidden fields to the table data region in the body section of the RDLC report layout. However, if there is more than one table data region in the report layout, then the header information is not displayed on pages that display the subsequent tables. Instead, it is only displayed on the page with the first table.

For reports such as document type reports that have multiple table data regions and require header information on each page, you must do the following steps:

  • Create hidden text boxes in the layout of one table to get the data.

  • Create a function to save the data, which you call from one or more hidden fields in the header section.

  • Create a function to retrieve the data, which you call from one or more displayed text boxes in the header section.

An example of a report that has multiple table data regions and uses functions to save and get header data is report 206, Sales - Invoice, in the standard application.

For more information about using hidden fields for information that will be displayed in headers or footers, see Understanding Headers and Footers.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To print header information on multiple pages

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Microsoft Visual Studio, on the Report menu, click Report Properties.

  5. In the Report Properties window, click the Code tab, and then add the following code to the Custom code text box.

    Note Note

    This example groups the data into four groups. You can modify the code if you need a different number of groups.

    Note Note

    To view this code in a report in the standard application, see report 206, Sales - Invoice.

    Visual Basic CopyCode image Copy Code
        Shared Data1 As Object
    Shared Data2 As Object
    Shared Data3 As Object
    Shared Data4 As Object

    Public Function GetData(ByVal Num As Integer, ByVal Group As Integer) as Object
        If Group = 1 Then
            Return Cstr(Choose(Num, Split(Cstr(Data1),Chr(177))))
        End If

        If Group = 2 Then
            Return Cstr(Choose(Num, Split(Cstr(Data2),Chr(177))))
        End If

        If Group = 3 Then
            Return Cstr(Choose(Num, Split(Cstr(Data3),Chr(177))))
        End If

        If Group = 4 Then
            Return Cstr(Choose(Num, Split(Cstr(Data4),Chr(177))))
        End If
    End Function

    Public Function SetData(ByVal NewData As Object, ByVal Group As Integer)
        If Group = 1 and NewData > "" Then
            Data1 = NewData
        End If

        If Group = 2 and NewData > "" Then
            Data2 = NewData
        End If

        If Group = 3 and NewData > "" Then
            Data3 = NewData
        End If

        If Group = 4 and NewData > "" Then
            Data4 = NewData
        End If
    End Function

  6. In the Body of the report.rdlc file, create one or more hidden text boxes to get the header data. For example, in report 206, four text boxes, which correspond to the four groups in the code, were created. The following table shows the names and values of the four text boxes.

    Name Value

    CustAddr

    =Fields!CustAddr_1_.Value + Chr(177) + Fields!CustAddr_2_.Value + Chr(177)+ Fields!CustAddr_3_.Value + Chr(177)+ Fields!CustAddr_4_.Value + Chr(177)+ Fields!CustAddr_5_.Value+Chr(177)+ Fields!CustAddr_6_.Value + Chr(177)+ Fields!CustAddr_7_.Value+Chr(177)+ Fields!CustAddr_8_.Value

    CompanyAddr

    =Fields!CompanyAddr_1_.Value + Chr(177) + Fields!CompanyAddr_2_.Value + Chr(177)+ Fields!CompanyAddr_3_.Value + Chr(177)+ Fields!CompanyAddr_4_.Value + Chr(177)+ Fields!CompanyAddr_5_.Value + Chr(177)+ Fields!CompanyAddr_6_.Value

    CompanyInfo

    =Fields!CompanyInfo__Phone_No__Caption.Value + Chr(177) + Fields!CompanyInfo__Phone_No__.Value + Chr(177) + Fields!CompanyInfo__Fax_No__Caption.Value + Chr(177) + Fields!CompanyInfo__Fax_No__.Value + Chr(177)+ Fields!CompanyInfo__VAT_Registration_No__Caption.Value + Chr(177)+ Fields!CompanyInfo__VAT_Registration_No__.Value + Chr(177)+ Fields!CompanyInfo__Giro_No__Caption.Value + Chr(177)+ Fields!CompanyInfo__Giro_No__.Value + Chr(177)+ Fields!CompanyInfo__Bank_Name_Caption.Value + Chr(177)+ Fields!CompanyInfo__Bank_Name_.Value + Chr(177)+ Fields!CompanyInfo__Bank_Account_No__Caption.Value + Chr(177)+ Fields!CompanyInfo__Bank_Account_No__.Value

    SalesHdrInfo

    =Fields!Sales_Invoice_Header___Bill_to_Customer_No__Caption.Value + Chr(177) +Fields!Sales_Invoice_Header___Bill_to_Customer_No__.Value + Chr(177) + Fields!VATNoText.Value + Chr(177) + Fields!Sales_Invoice_Header___VAT_Registration_No__.Value + Chr(177) + Fields!ReferenceText.Value + Chr(177) + Fields!Sales_Invoice_Header___Your_Reference_.Value + Chr(177) + Fields!Invoice_No_Caption.Value + Chr(177) + Fields!Sales_Invoice_Header___No__.Value + Chr(177) + Fields!OrderNoText.Value + Chr(177) + Fields!Sales_Invoice_Header___Order_No__.Value + Chr(177) + Fields!Sales_Invoice_Header___Posting_Date_Caption.Value + Chr(177) + Fields!Sales_Invoice_Header___Posting_Date_.Value + Chr(177) + Fields!Sales_Invoice_Header___Due_Date_Caption.Value + Chr(177) + Fields!Sales_Invoice_Header___Due_Date_.Value + Chr(177) + Fields!Sales_Invoice_Header___Prices_Including_VAT_Caption.Value + Chr(177) + Cstr(Fields!PricesInclVAT_YesNo.Value) + Chr(177) + First(Fields!FORMAT__Sales_Invoice_Header___Document_Date__0_4_.Value) + Chr(177) + First(Fields!STRSUBSTNO_DocumentCaption_CopyText_.Value) + Chr(177) + Fields!SalesPersonText.Value + Chr(177) + Fields!SalesPurchPerson_Name.Value + Chr(177) + Fields!PageCaption.Value
    Note Note

    Chr(177) is used here to separate the data in each group. When you call the GetData function, it splits the data in the group by using Chr(177) as a separator.

    For more information about creating hidden fields, see How to: Add and Identify Hidden Fields.

  7. In the Header of the report.rdlc file, create one or more hidden text boxes to save the data from the text boxes in the Body section. For example, in report 206, four text boxes with the following values were created:

    • =Code.SetData(ReportItems!CustAddr.Value,1)

    • =Code.SetData(ReportItems!CompanyAddr.Value,2)

    • =Code.SetData(ReportItems!CompanyInfo.Value,3)

    • =Code.SetData(ReportItems!SalesHdrInfo.Value,4)

    The first parameter in each SetData function call corresponds to the name of the text box in the Body section. The second parameter corresponds to the group number.

    For more information about creating hidden fields, see How to: Add and Identify Hidden Fields.

  8. In the Header of the report.rdlc file, create the text boxes for displaying data. The source expression for each text box must call the GetData function with the following two parameters:

    • The number of the variable in the group

    • The number of the group

    For example, Code.GetData(2,1) gets the second piece of data from group 1, which is CustAddr_2_.Value in the CustAddr group.

  9. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Redesign Blank Lines

How to: Redesign Blank Lines

If you create a client report definition (RDLC) layout for a report, blank lines that appear in the Classic report layout do not appear in the RDLC layout. To add blank lines to an RDLC report layout, you must add a BlankLineCounter section to the Classic report layout. Next, you must add lines to the table in the new layout and modify the expression in the Visible field in each line to specify the conditions on which to display the blank lines.

An example of a report in the standard application to which a BlankLineCounter is added in the Classic report layout and blank lines are added in the RDLC report layout is report 1, Chart of Accounts.

Before you begin this procedure, you must create a layout suggestion. For more information, see How to: Create a Layout Suggestion.

To add a BlankLineCounter section to a report

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report that has blank lines, and then click Design.

  3. On the View menu, click Sections.

  4. In Section Designer, select the section above or below which you want to add blank lines, click the Edit menu, and then click New.

  5. In the Insert New Section window, in the Data Item field, select BlankLineCounter from the drop-down list.

  6. Under Section Type, select Body.

  7. Under Insert Section, select the location where you want to insert the blank lines, and then click OK.

  8. On the File menu, click Save.

  9. In the Save window, select the Compiled check box, and then click OK.

To add blank lines to a report.rdlc file

  1. In Object Designer, click Report, select the report that has blank lines, and then click Design.

  2. On the View menu, click Layout.

  3. In Microsoft Visual Studio, in the Report.rdlc file, select the table row where you added the BlankLineCounter section.

  4. Above the row that you selected in step 3, insert the maximum number of blank lines that you want inserted between lines.

  5. For each blank line that you added, do the following to adjust the height and the conditional visibility:

    1. Select the line.

    2. On the View menu, click Properties Window.

    3. In the Properties window, under Layout, enter 0.423cm in the Height field.

    4. In the Properties window, under Visibility, in the Hidden field, select <Expression…> from the drop-down list.

    5. Enter a conditional statement in the Edit Expression window so that the line is not hidden if the number of blank lines is great than 0 for the first line, or greater than 1 for the second line, and so on. The following statement is an example of the expression.

      CopyCode image Copy Code
      =IIF(Fields!G_L_Account___No__of_Blank_Lines_.Value>0,FALSE,TRUE)

  6. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Redesign Footers

How to: Redesign Footers

Footers in client report definition (RDLC) report layouts have limitations that require you to add hidden fields to the body of the report that contain the data that you want to display in the footer. The field in the footer references the hidden field in the body. For more information about headers and footers, see Understanding Headers and Footers.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To redesign page footers

  1. Add a hidden field to the body section of the report. The SourceExpr field should contain the field that you want to use in the footer. For more information, see How to: Add and Identify Hidden Fields.

  2. In Object Designer, click Report, select the report, and then click Design.

  3. In the Classic client, on the View menu, click Layout.

  4. In Microsoft Visual Studio, on the Report menu, click Page Footer to create a page footer in the RDLC report layout.

  5. To display data in the footer from the hidden field that you created in step 1, use ReportItems. For example, use the following to get the value of a text box.

    CopyCode image Copy Code
    =ReportItems!MyTextBox.Value

    In this example, MyTextBox is the name of the text box that you created in step 1.

  6. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

See Also

Concepts

Understanding Headers and Footers
Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Redesign the Number of Copies Option

How to: Redesign the Number of Copies Option

For document type reports, often the request form displays an option for number of copies to print. In a client report definition (RDLC) report layout, a copy is the same as a new document that must start on a new page. You must add code to set and update the copy number, group the data based on the copy number, and then specify a page break at the end of the group.

Before you begin this procedure, you must create the RDLC layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To add code to the report for the number of copies

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report that you want to modify to print multiple copies, and then click Design.

  3. On the View menu, click C/AL Globals.

  4. In the C/AL Globals window, on the Variables tab, add the following variable.

    Name DataType

    OutputNo

    Integer

  5. In Report Designer, select the CopyLoop data item.

  6. On the View menu, click C/AL Code.

  7. In the C/AL Editor, add the following code to the OnPreDataItem trigger to create and initialize the new page number variable.

    CopyCode image Copy Code
    IF ISSERVICETIER THEN
  OutputNo := 1;

  8. In the C/AL Editor, modify the existing code in the OnAfterGetRecord trigger to increment the page number variable.

    CopyCode image Copy Code
    IF Number > 1 THEN BEGIN // Existing line
  CopyText := Text003;   // Existing line
  IF SERVICETIER THEN    // Added line
    OutputNo += 1;       // Added line
END;                     // Existing line

  9. On the View menu, click Sections.

  10. In the PageLoop Header section, add a hidden text box whose SourceExpr is the page number variable. For example, in report 206, there is a hidden text box for the OutputNo variable. For more information, see How to: Add and Identify Hidden Fields.

  11. On the File menu, click Save.

  12. In the Save window, select the Compiled check box, and then click OK.

To group data based on copy number

  1. In the Classic client, on the View menu, click Layout.

  2. In Microsoft Visual Studio, in the report.rdlc file, right-click the row that you want to group on, and then click Edit Group.

  3. In the Grouping and Sorting Properties window, on the General tab, under Group on, select the next blank line to add a grouping, and then select =Fields!OutputNo.Value from the drop-down list.

  4. In the Grouping and Sorting Properties window, click the Sorting tab.

  5. Select a blank line, and then select =Fields!OutputNo.Value from the drop-down list.

  6. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.


How to: Redesign Option Strings in Multilanguage Implementations

How to: Redesign Option Strings in Multilanguage Implementations
See Also

On Classic report layouts that use an option variable, you can use the option string of the option variable to determine which option was selected by the end user. In a client report definition (RDLC) report layout, an option variable is handled as a normal string, not an option string. If you have a multilanguage application, handling the option as a normal string will cause problems in the displayed report. You must manually convert the option string to an integer variable and then use the integer variable in the RDLC report layout.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To assign the option string to an integer variable

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report that you want to modify, and then click Design.

  3. On the View menu, click C/AL Globals.

  4. In the C/AL Globals window, on the Variables tab, add the following variable.

    Name DataType

    ShowTypeNo

    Integer

  5. Close the C/AL Globals window to save your changes.

  6. On the View menu, select C/AL Code.

  7. In the C/AL Editor, add the following code to the OnAfterGetRecord trigger to assign the option string to an integer value.

    CopyCode image Copy Code
    IF ISSERVICETIER THEN BEGIN
  ShowTypeNo := ShowType;
END;

  8. On the View menu, click Sections.

  9. Add a hidden text box with ShowTypeNo as the value of the SourceExpr field. For more information, see How to: Add and Identify Hidden Fields.

  10. On the File menu, click Save.

  11. In the Save window, select the Compiled check box, and then click OK.

To use the integer variable instead of the option string

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Microsoft Visual Studio, in the Report.rdlc file, use the integer variable wherever you used the option string, such as in expressions.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Redesign Section Triggers that Calculate Percentage

How to: Redesign Section Triggers that Calculate Percentage

On some reports that show percentages, the function that calculates the percentage is on one or more section triggers. In client report definition (RDLC) report layouts, code on section triggers is not supported. You must add a function to the report to calculate the percentage and modify fields in the Report.rdlc file so that they call the function. For example, in the standard application, report 113, Customer/Item Sales, uses the CalcPct function to calculate profit percentages.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To transform section triggers that calculate percentage

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Microsoft Visual Studio, in the Report.rdlc file, on the Report menu, select Report Properties.

  5. In the Report Properties window, select the Code tab.

  6. Add the following code in the Custom code text box:

    Visual Basic CopyCode image Copy Code
        Shared Pct As Decimal
    Public Function CalcPct(ByVal Amount As Decimal, ByVal Profit As Decimal) As Decimal
        If Amount <> 0 Then
            Pct = 100 * Profit / Amount
        Else
            Pct = 0
        End If
        REM Rounding precision = 0.1
        Return ROUND(10 * Pct) / 10
    End Function
    Note Note

    This code is also available in report 113, Customer/Item Sales.

  7. Click OK.

  8. In Visual Studio, in the Report.rdlc file, right-click each text box to display a percentage, and then click Expression.

  9. In the Expression window, enter the following expression:

    CopyCode image Copy Code
    =Code.CalcPct(<Fields!Amount.Value>,<Fields!Profit.Value>)

    The amount and profit parameters that you pass to the CalcPct function are lookup values from the Microsoft Dynamics NAV table.

    Note Note

    In report 113, Customer/Item Sales, the expressions in the Profit % column, which is the column on the right of the report, call the CalcPct function. For example, the first expression in the column is =Code.CalcPct(Fields!ValueEntryBuffer__Sales_Amount__Actual___Control44.Value, Fields!Profit_Control46.Value).

  10. Click OK.

See Also

Tasks

How to: Verify Code on a Report

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Redesign SourceExpr Values in Conditionally Visible Sections

How to: Redesign SourceExpr Values in Conditionally Visible Sections
See Also

In the Classic client, you can show or hide a section of a report based on a condition. For example, section A of a report is shown only for customers that have a Customer No. value in a given range. You can show or hide a section conditionally by calling CurrReport.SHOWOUTPUT(<expr>) in the OnPreSection trigger of the report. If expr is false, then the section is not displayed, and the SourceExpr values of the controls in the section are not evaluated.

You can also have a report with a control that calls a function in the conditionally displayed section. For example, a SourceExpr value of a control can call the CLOSINGDATE function on a date variable. The OnPreSection trigger of the report determines whether the section is displayed. The expression that is evaluated in CurrReport.SHOWOUTPUT(<expr>) and the date variable on which the CLOSINGDATE function is called are related so that if expr is true, then the date variable is an initialized variable. If expr is false, then the date variable is not initialized. If CLOSINGDATE is called on a variable that is not initialized, then the a run-time error occurs. However, in this case, expr is false, so the section is not displayed, and the SourceExpr of the control is not evaluated. The CLOSINGDATE function is not called.

In a client report definition (RDLC) layout, section triggers are not supported. When you create an RDLC layout suggestion for this report, the OnPreSection trigger is not included. Additionally, all data for the report is calculated on Microsoft Dynamics NAV Server before it is sent to the client to be displayed. The CLOSINGDATE function is called even if the date variable is not initialized, and a run-time error occurs.

To redesign the RDLC report layout for this type of report, you must write C/AL code for the SourceExpr value that verifies the data that is passed to the function and then calls the function. That way, CLOSINGDATE is called only if the data is initialized. Otherwise, the SourceExpr value evaluates to null.

To redesign code that is executed conditionally

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click C/AL Globals.

  4. In the C/AL Globals window, click the Functions tab.

  5. Enter a name for the new function. For example, enter SafeClosingDate to create a function to use instead of the CLOSINGDATE function.

  6. Click Locals to define the parameters, return value, local variables, and text constants in the C/AL Locals window. For example, define the following values:

    • On the Parameters tab, enter SourceDate for the name of a parameter and enter Date for the DataType.

    • On the ReturnValue tab, enter NewClosingDate for the name of the return value and enter Date for the return type.

    • On the Variables tab, enter UndefinedDate for the name of a variable and enter Date for the data type.

  7. Close the C/AL Locals window.

  8. On the View menu, click C/AL Code.

  9. In the C/AL Editor, enter code for the new function that you defined. For example, enter the following code for the VerifyClosingDate function.

    CopyCode image Copy Code
    UndefinedDate := 0D;
IF(SourceDate = UndefinedDate) THEN
    EXIT(UndefinedDate);
ELSE
    EXIT(CLOSINGDATE(SourceDate));

  10. If you have not transformed the report to an RDLC report layout, then complete the following steps:

    1. On the View menu, click Sections.

    2. In the section that is displayed based on a condition, select the control that calls the function that you want to replace, and on the View menu, click Properties.

    3. In the Properties window, in the SourceExpr field, enter the function call to the new function that you created. For example, enter SafeClosingDate(<Date variable>).

    4. Save and compile the report.

    5. On the Tools menu, click Create Layout Suggestion to create an RDLC layout for the report.

  11. If you have already transformed the report to an RDLC report layout, then complete the following steps:

    1. On the View menu, click Layout.

    2. On the View menu, select the control that calls the function that you want to replace.

    3. Replace the call to the CLOSINGDATE function with a call to the SafeClosingDate function.

See Also

Tasks

How to: Verify Code on a Report

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Reset Page Numbers

How to: Reset Page Numbers

On some reports, you may want to group sets of data together and reset the page number after each group. For example, in the standard application, report 206, Sales Invoice, displays sales invoices that are grouped by sales invoice number. To reset the page number to 1 for each group of data, you must modify code on the client report definition (RDLC) report layout.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To reset page numbers

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Microsoft Visual Studio, in the Report.rdlc file, on the Report menu, select Report Properties.

  5. In the Report Properties window, select the Code tab.

  6. Add the following code in the Custom code text box:

    Visual Basic CopyCode image Copy Code
    REM Reset Page Number:

    Shared offset As Integer
    Shared newPage As Object
    Shared currentgroup1 As Object
    Shared currentgroup2 As Object
    Shared currentgroup3 As Object

    Public Function GetGroupPageNumber(ByVal NewPage As Boolean, ByVal pagenumber As Integer) As Object
        If NewPage Then
            offset = pagenumber - 1
        End If
        Return pagenumber - offset
    End Function

    Public Function IsNewPage(ByVal group1 As Object, ByVal group2 As Object, ByVal group3 As Object) As Boolean
        newPage = False
        If Not (group1 = currentgroup1) Then
            newPage = True
            currentgroup1 = group1
        Else
            If Not (group2 = currentgroup2) Then
                newPage = True
                currentgroup2 = group2
            Else
                If Not (group3 = currentgroup3) Then
                    newPage = True
                    currentgroup3 = group3
                End If
            End If
        End If
        Return newPage
    End Function
    Note Note

    This code is also available in report 206, Sales Invoice.

  7. Click OK.

  8. In Visual Studio, in the Report.rdlc file, right-click the text box in the header that displays the page number, and then select Expression.

  9. In the Expression window, enter the following expression.

    CopyCode image Copy Code
    =Code.GetGroupPageNumber(ReportItems!NewPage.Value,Globals!PageNumber)

    The NewPage.Value parameter is the value of the NewPage text box, which you create in step 8.

  10. Click OK.

  11. In the Body section of the layout, create a new text box called NewPage.

  12. Right-click the NewPage text box that you created in step 8 and then select Properties.

  13. In the Properties window, on the General tab, enter the following in the Value field.

    CopyCode image Copy Code
    =Code.IsNewPage(Fields!<grouping field1>[,<grouping field2>,<grouping field3>])

    For example, if you are grouping by document type, then grouping field1 would be Document_Type.Value.

    Note Note

    If you want to use more than three groupings, you can modify the code in the IsNewPage function. If you want to use fewer than three groupings, you can either modify the code in the IsNewPage function or use a static value for one or more of the parameters.

  14. Click OK.

See Also

Tasks

How to: Print Header Information on Multiple Pages

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Resolve Formatting Issues Caused by Hidden Fields

How to: Resolve Formatting Issues Caused by Hidden Fields

Some client report definition (RDLC) report layouts have hidden fields in the body section of the layout. Even though these fields are hidden, in some reports they will cause formatting problems when you print the report because they are outside the width of standard paper or are outside the margins of the page setup. To eliminate the formatting problems, you must move these hidden fields to another location on the report that is within the width of standard paper or within the margins of the page setup. We recommend that you add the fields to an additional row in the table and minimize the width of that row.

For more information about using hidden fields in the body of an RDLC report layout, see Understanding Headers and Footers.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To resolve formatting problems that are caused by hidden fields

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Visual Studio, in the Body of the report.rdlc, verify whether there are hidden fields in the right-most columns of the table.

  5. Right-click the hidden fields, and then click Cut.

  6. Insert a new row in the table.

  7. Right-click the first field in the new row, and then click Paste.

  8. Select the new row. In the Properties window, under Layout, change the value of the Height property to 0.2cm. The height of 0.2 cm is large enough that you can view the row in the layout, but small enough that it will not cause formatting problems when you print the report.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Specify Rounding Precision

How to: Specify Rounding Precision
See Also Example

In Visual Studio Report Designer, you can use the ROUND function to round a double-precision floating point value to the nearest integer. However, this function does not have options for changing the precision to which you want to round. For example, you cannot round to the nearest tenth or nearest hundredth of a number, only to the nearest integer. To specify precision when using the ROUND function, you must multiply the number by a factor of 10, call the ROUND function, and then divide the rounded number by the same factor of 10. The factor that you choose depends on the degree of precision that you want. For example, if you want to round the number 12.3456 to the nearest hundredth, you would multiply 12.3456 by 100 to get 1234.56. Next, call the ROUND function on 1234.56. The ROUND function rounds to the nearest integer, resulting in the number 1235. Finally, divide the rounded number, 1235, by the factor, 100, to get 12.35. This result is the same as rounding the original number, 12.3456, to the nearest hundredth.

To specify precision when you use the ROUND function on a client report definition (RDLC) report layout, you must do one of the following:

  • Use an expression, such as =ROUND(100*<Value>)/100 on the value in a text box.

  • Add code to functions that call the ROUND function.

An example of a report in the standard application that uses the ROUND function and specifies a degree of precision is report 111, Customer - Top 10 List.

Before you begin this procedure, you must create the layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To use an expression to specify rounding precision

  1. In the Classic client, click Tools, and then click Object Designer.

  2. In Object Designer, click Report, select a report that contains a number that you want to round with precision greater than the nearest integer, and then click Design.

  3. In the View menu, click Layout.

  4. In Visual Studio, in the Report.rdlc file, right-click the text box with the number that you want to round, and then click Expression.

  5. In the Expression window, change the expression to the following.

    CopyCode image Copy Code
    =ROUND(<MyField.Value>*<Factor>)/<Factor>

    In this example, MyField.Value is the numerical value that you want to round. Factor is a factor of 10, and depends on the degree of precision that you want.

  6. Click OK to close the Expression window.

  7. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

To add code to specify rounding precision

  1. In the Classic client, click Tools, and then click Object Designer.

  2. In Object Designer, click Report, select a report that contains a number that you want to round with precision greater than the nearest integer, and then click Design.

  3. In the View menu, click Layout.

  4. In Visual Studio, in the Report.rdlc file, in the Report menu, select Report Properties.

  5. In the Report Properties window, select the Code tab.

  6. Add the following lines of code to the function in which you want to specify rounding precision. The code that you add may vary, depending on the degree of precision that you want. In this example, the rounding precision is 0.01.

    CopyCode image Copy Code
    REM Rounding precision = 0.01
Return ROUND(100*Pct)/100

  7. Save and compile the report. For more information, see How to: Integrate Classic Client Report Designer and Visual Studio Report Designer.

Example

The following code example shows a function that calls the ROUND function and uses the preceding procedure to specify precision.
CopyCode image Copy Code
Shared Pct as Decimal
Public Function CalcPct(Amount1 as Decimal, Amount2 as Decimal) as Decimal
   if Amount2 <> 0 then
      Pct = Amount1 / Amount2 * 100
   else
      Pct = 0
   end if
   REM Rounding precision = 0.1
   Return ROUND(10*Pct)/10
End Function

The following illustration shows how to call the CalcPct function for the value of a text box.

See Also

Tasks

How to: Redesign Section Triggers that Calculate Percentage


How to: Verify Code on a Report

How to: Verify Code on a Report
See Also Example

Some code that is supported on Classic report layouts is not supported on client report definition (RDLC) report layouts. If you want to use the RDLC layout of a report, you should verify that all code on your report is supported in the RDLC layout. If code on your report is not supported, then you must move or modify the code.

In some cases, you can use the new report layout functionality to achieve the same result as the unsupported code. For example, some reports have code in a section trigger that specifies whether an item in a report will be visible or not. In the RDLC report layout, code on section triggers is not supported. You can use an expression for the Visibility property instead of code on a section trigger. For more information, see How to: Apply Conditional Visibility Controls.

To verify code on a report

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report, and then click Design.

  3. On the View menu, click C/AL Code.

  4. Verify that the report does not call unsupported functions. If a report does call an unsupported function, determine how to achieve the same functionality by moving or modifying the code or by using new report layout functionality.

  5. Close the C/AL Editor.

  6. On the View menu, click Sections.

  7. In Section Designer, right-click each section, and then select C/AL Code.

  8. Verify that the report does not have code on any section triggers. If a report does have code on a section trigger, determine how to achieve the same functionality by moving or modifying the code or by using new report layout functionality.

  9. On the File menu, click Save.

  10. In the Save window, select the Compiled check box, and then click OK.

Example

Microsoft Dynamics NAV 2009 includes IsServiceTier, which is a new system variable. If you need to modify code on a report, you may need different code to run depending on whether you are running the Classic report layout or the RDLC report layout. Use the IsServiceTier variable to determine which block of code to run.

If the return value of IsServiceTier is true, then the code is being run on Microsoft Dynamics NAV Server. If IsServiceTier is false, then the code is being run on the Classic client.

The following example shows how to use the IsServiceTier variable.
CopyCode image Copy Code
IF IsServiceTier THEN BEGIN
   <code to run on Microsoft Dynamics NAV Server>;
END ELSE BEGIN
   <code to run on Classic client>;
END;

To see an example of the use of the IsServiceTier variable in a report, view the C/AL code on Report 111, Customer - Top 10 List.

See Also

Tasks

How to: Redesign Section Triggers that Calculate Percentage
How to: Apply Conditional Visibility Controls
How to: Redesign the Number of Copies Option
How to: Redesign Option Strings in Multilanguage Implementations
How to: Create New Pages per Record


How to: Verify Controls on a Report

How to: Verify Controls on a Report

Client report definition (RDLC) report layouts generate the dataset for the reports in a different way than Classic report layouts. For RDLC report layouts, the dataset is generated based on a set of rules and uses the controls in the section part of the Classic report layout. To get an RDLC report layout with controls and labels shown together and with correct names on labels, we recommend that for every control that has a label, you connect the control to the label.

To verify existing controls on a report

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report that you want to verify, and then click Design.

  3. On the View menu, click Sections.

  4. For every control on the report that has a label, verify that the control is connected to the label with the following steps:

    1. In Section Designer, select the label that is associated with the control. On the View menu, click Properties.

    2. In the Label - Properties window, verify that the value of the ParentControl property is the ID of the control for this label.

  5. On the File menu, click Save.

  6. In the Save window, select the Compiled check box, and then click OK.

See Also

Concepts

Understanding Report Redesign


How to: Verify Page Headers and Table Headers

How to: Verify Page Headers and Table Headers

The Classic client layout of a report has one or more header sections and a body section. The body section of the report contains the report data in a table format. In the client report definition (RDLC) report layout of some reports, some header information for the table is in the header section of the report layout instead of the body section with the remaining rows of the table. You must verify that all table header information is in the body of the report layout with the remaining rows of the table or move the table header information if it is not.

Before you begin this procedure, you must create a layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To verify page headers and table headers

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Microsoft Visual Studio, in the Report.rdlc file, verify that the fields in the header sections of the layout are not specific to the columns of the table, which is in the body section of the layout.

    In the following illustration, some fields in the Page Header section are specific to the table and must be moved to the Body section.

  5. Right-click the fields that are specific to columns in the table that you will move to the body section of the layout, and then click Cut.

  6. Right-click the first row of the table in the body section, and then click Insert Rows Above.

  7. Right-click the first field in the new row, and then click Paste.

    In the following figure, the fields have been moved from the Page Header section to the table in the Body section.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Verify the Paper Size

How to: Verify the Paper Size

Before you print or preview a client report definition (RDLC) report layout, the RoleTailored client checks the page width and page height to verify that the paper size is supported by the printer. After you create an RDLC report layout, to ensure that you can print and preview the report, you must verify that the page width and page height properties are valid.

The following table shows valid paper size dimensions.

Paper size | Width | Height
A4 | 21 cm | 29.7 cm
Letter | 8.5 inches | 11 inches

Before you begin this procedure, you must create the layout suggestion for the report. For more information, see How to: Create a Layout Suggestion.

To verify the page height and page width properties

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select a report that you want to modify, and then click Design.

  3. On the View menu, click Layout.

  4. In Microsoft Visual Studio, in the Report.rdlc file, click the Report menu, and then click Report Properties.

  5. In the Report Properties window, on the Layout tab, verify that the values in the Page width and Page height fields are valid.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Verify TrueType Fonts

How to: Verify TrueType Fonts

In client report definition (RDLC) report layouts, only TrueType fonts are supported. If you have a report that uses a font that is not a TrueType font, such as Helvetica, when you transform the report, the font will be changed to Arial. For more information, see Microsoft Typography - TrueType fonts.

Note Note

The available TrueType fonts for the operating system are listed under the following registry subkey: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts

To use both Classic report layouts and RDLC report layouts and have the same fonts in both layouts, you must change non-TrueType fonts to TrueType fonts in the Classic report layout. When you create an RDLC layout suggestion or view the RDLC layout for the report, the RDLC report layout then has the same TrueType font as the Classic report layout.

To change a font from a TrueType font

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select the report that you want to modify, and then click Design.

  3. On the View menu, click Sections.

  4. In Section Designer, select a text box that you want to change, click the View menu, and then click Properties.

  5. In the Properties window, in the FontName field, if the selected font is not a TrueType font, then enter a font that is a TrueType font, such as Arial.

  6. On the File menu, click Save.

  7. In the Save window, select the Compiled check box, and then click OK.

See Also

Concepts

Understanding Report Redesign
Designing Reports for the RoleTailored Client


How to: Transform the Request Form

How to: Transform the Request Form

After you create a client report definition (RDLC) layout suggestion for a report, you must transform the request form, which allows you to select filters for the report, to a request page. To do this, you use the form transformation tool.

Request forms and request pages are stored as part of the report. They are not stored as separate forms. To transform the request form to a request page, you run the form transformation tool on the exported report in .xml format.

Before you begin this procedure, confirm that a request page for the report does not already exist.

Note Important

You cannot transform a report that already contains a request page from a previous transformation. When you transform a request form, not only is the request page stored as part of the report, but also variables, functions, and constants are stored as part of the report. This is different from transforming forms in which any additional code is added to a new page object.

If you transform a request form more than once you will have multiple copies of the new variables, functions, and constants.

To transform the request form

  1. Install the form transformation tool. For more information, see How to: Install the Form Transformation Tool.

  2. In the Classic client, click Tools, and then click Object Designer.

  3. In Object Designer, click Report, and then select the report for which you want to transform the request form.

  4. In the File menu, select Export.

  5. In the Export Objects window, enter a name for the exported file. We recommend that you name the file Forms.xml. Browse to the folder where the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file is located, and then click Save.

  6. Verify that the file names in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file are correct. For example, verify the following two lines:

    <add key="FormsFile" value=".\Forms.xml"/>

    <add key="PagesFile" value=".\Pages.xml"/>

  7. Run the form transformation tool. For more information, see How to: Run the Form Transformation Tool.

  8. Import and compile the page .xml file. The name of the .xml file to import is the name of the output .xml file that you specified in step 6. For more information, see How to: Import, Compile, and Run Transformed Pages.

Viewing the Request Page

After you transform the request form to a request page, you can run the report in the RoleTailored client to view the request page. You can also view the request page in the Classic client. If you want to modify the request page after you transform it, you must view the page by using Object Designer in the Classic client. Use the following procedure to view the request page in the Classic client.

To view the request page in the Classic client

  1. In the Classic client, click Tools, and then click Object Designer.

  2. In Object Designer, click Report, select the report with the request page that you want to view, and then click Design.

  3. In the View menu, select Request Page.

See Also

Concepts

Transforming Forms to Pages


Walkthrough: Redesigning a Customer List Report

Walkthrough: Redesigning a Customer List Report

In this walkthrough, you will learn how to redesign the Customer List report from a Classic report layout to a client report definition (RDLC) report layout.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Using the create layout suggestion function to suggest an RDLC layout for the report.

  • Manually modifying the RDLC layout.

  • Saving the layout and compiling the report.

  • Transforming the report request form with the form transformation tool.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements met. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.

  • Microsoft Visual Web Developer or Visual Studio installed. For more information, see the Requirements for Additional Features and Options section of Classic Client Requirements in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.

  • Basic knowledge of Visual Studio Report Designer. For more information, see Report Designer (Visual Studio).

Expand image Story

Simon is a Microsoft Certified Partner working for CRONUS International Ltd. He has been asked to create an RDLC layout for the Customer List report that CRONUS currently uses with the Classic client.

Expand image Creating the Suggested Layout

The create layout suggestion function automatically suggests an RDLC report layout. Use the following procedure to create the suggested layout and view it in Visual Studio.

To create the suggested layout

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select Report 101, Customer List, and then click Design.

  3. On the Tools menu, select Create Layout Suggestion. A suggestion for an RDLC report layout is created.

    Note Note

    If you have already created a layout suggestion or have edited this report layout in Visual Studio, a message is displayed and asks if you want to overwrite the existing layout. Because report 101 is a standard application report, it already has an RDLC layout. For the purpose of this walkthrough, you can overwrite the existing layout. If you want to edit the existing layout instead of creating a new layout suggestion, on the View menu, click Layout.

    Note Note

    You must complete the additional checks and manual modifications in the following procedures before the report layout is complete.

Expand image Modifying the Customer List Report RDLC Layout

Hidden fields in the RDLC report layout will cause formatting problems when you print the report because these fields are outside the width of standard paper. To eliminate the formatting problems, you must move these hidden fields to another location on the report that is within the width of standard paper..

To move the hidden fields

  1. In Visual Studio, in the Report.rdlc file that was created, in the Body section of the layout, select the following hidden fields on the right side of the table:

    • =FIELDS!COMPANYNAME.VALUE

    • =FIELDS!Customer__ListCaption.VALUE

    • =FIELDS!CurrReport_PAGENOCaption.Value

  2. Right-click the selected fields, and then click Cut.

  3. Right-click the row handle of the last row, and then click Insert Row Below to insert a new row in the table.

  4. Right-click the first field in the new row, and then click Paste.

  5. On the View menu, click Properties Window.

  6. Select the new row. In the Properties window, under Layout, change the value of the Height property to 0.2cm. The height of 0.2 cm is large enough that you can view the row in the layout but small enough that it will not cause formatting problems when you print the report.

This report has unsupported code for the RoleTailored client on the section trigger for Customer, Header (3). You must add the functionality for this code elsewhere in the report so that it will run in the RoleTailored client report.

Note Note

If you plan to use the Classic report layout, then you need to keep the unsupported code. When you run the report in the Classic client, this code will run.

To add the functionality from the section trigger

  1. In Visual Studio, on the View menu, click Properties Window.

  2. In the Report.rdlc file, in the Body section of the layout, select the field at the top of the layout with the following value:

    • =First(Fields!Customer_TABLECAPTION__________CustFilter.Value)

  3. In the Properties window, under Appearance, expand Visibility.

  4. In the drop-down list for the Hidden field, select <Expression>.

  5. In the Expression window, enter the following expression: =IIF(Fields!CustFilter.Value<>"",False,True)

  6. Click OK.

Expand image Saving the RDLC Report Layout

You must save the RDLC layout, and you must also save and compile the changes in the Classic client.

To save the report

  1. In Visual Studio, on the File menu, click Save report.rdlc.

    Note Note

    If you close the report in Object Designer in the Classic client and then make changes in Visual Studio Report Designer and try to save the RDLC layout, then you will get the Save As dialog box. This is because the RDLC layout that you are trying to save is not connected to Object Designer. When you closed the report in Object Designer, the version of the RDLC layout that was connected to Object Designer was saved in the report, and then deleted.

  2. Close Visual Studio.

  3. In the Classic client, select an empty line in the report in Object Designer. The following message appears:

    The layout of report id: '101' is changed by another application.

    Filename of the changed RDLC: <filename>

    Do you want to load the changes?

  4. Click Yes to load the changes that you made to the RDLC layout in the Classic client.

  5. On the File menu, click Save.

  6. In the Save dialog box, select Compiled, and then click OK.

  7. Close the report in Object Designer.

Expand image Transforming the Request Form

In addition to creating an RDLC layout for the report, you must use the form transformation tool to transform the request form that allows you to select filters for the report.

To transform the request form

  1. Install the form transformation tool. For more information, see How to: Install the Form Transformation Tool.

  2. In the Classic client, on the Tools menu, click Object Designer.

  3. In Object Designer, click Report, and then select Report 101, Customer List.

  4. On the File menu, click Export.

  5. In the Export Objects window, enter Report101_Forms.xml for the name of the file. Browse to the folder where the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file is located, and then click Save.

  6. Edit the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file.

    • Change the name of the Forms.xml file to Report101_Forms.xml.

      CopyCode image Copy Code
      <add key="FormsFile" value=".\Report101_Forms.xml" />

    • Change the name of the output pages.xml file to Report101_Pages.xml.

      CopyCode image Copy Code
      <add key="PagesFile" value=".\Report101_Pages.xml" />

  7. Run the form transformation tool. For more information, see How to: Run the Form Transformation Tool.

  8. In the Classic client, click Tools, and then click Object Designer.

  9. On the File menu, click Import.

  10. In the Import Objects window, in the Files of type drop-down list, select XML Format (*.xml), browse to the folder where the Report101_Pages.xml file is located, select Report101_Pages.xml, and then click Open.

  11. In Object Designer, click Report, and select report 101.

  12. On the Tools menu, click Compile, and then click Yes.

  13. To view the RDLC report layout, type the following command at a command prompt:

    DynamicsNAV:////runreport?report=101


Walkthrough: Redesigning a Customer - Order Summary Report

Walkthrough: Redesigning a Customer - Order Summary Report

In this walkthrough, you will learn how to create and modify a client report definition (RDLC) report layout for a Customer - Order Summary report.

The Customer - Order Summary report is based on the following tables:

  • Customer

  • Sales Line

To create an RDLC report layout with the same functionality that you have in the Classic client report layout, you must perform some manual steps. These manual steps add data and improve the layout of the report.

Expand image About This Walkthrough

This walkthrough provides an overview of how to create and modify an RDLC layout for a Customer - Order Summary report. This walkthrough illustrates the following tasks:

  • Using the create layout suggestion function to suggest an RDLC layout for the report.

  • Manually modifying the RDLC report layout.

  • Saving the layout and compiling the report.

  • Transforming the report request form using the form transformation tool.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements met. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.

  • Microsoft Visual Web Developer or Visual Studio installed. For more information, see the Requirements for Additional Features and Options section of Classic Client Requirements in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.

  • Basic knowledge of Visual Studio Report Designer. For more information, see Report Designer (Visual Studio).

Expand image Story

Simon is a Microsoft Certified Partner working for CRONUS International. He has been asked to create an RDLC layout for the Customer - Order Summary report that CRONUS currently uses with the Classic client.

Expand image Creating the Suggested Transform Layout

The create layout suggestion function automatically suggests a report layout. Use the following procedure to create the suggested layout and view it in Visual Studio.

To create the suggested transform layout

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Report, select Report 107, Customer - Order Summary, and then click Design.

  3. On the Tools menu, click Create Layout Suggestion. A suggestion for an RDLC report layout is created.

The following illustration shows the RDLC report layout for report 107, Customer - Order Summary, after you create the suggested layout but before you perform any manual modifications.

Expand image Modifying the Customer - Order Summary Report RDLC Layout

The RDLC report layout for the Customer - Order Summary report that is created by using the create layout suggestion function does not contain all the lines that you want to view in the report. You must make some modifications to the report layout.

To move header fields out of the table

  1. In Visual Studio, in the Body of the report.rdlc file, move the table down in the layout to provide space for two fields above the table.

  2. Select the First(Fields!Outstanding_OrdersCaption.Value) field, right-click the field, and then click Cut.

  3. Right-click the area above the table and then click Paste to paste the First(Fields!Outstanding_OrdersCaption.Value) value in a text box above the table.

  4. Select the First(Fields!EmptyString.Value) field, right-click, and then select Cut.

  5. Right-click the area above the table, just below the text box that was created in step 3, and then click Paste to paste the First(Fields!EmptyString.Value) value in a text box.

  6. Select the first two rows of the table from which you cut fields. Right-click the row handle of the two rows, and then select Delete Rows.

The suggested layout that is created automatically contains some fields that you must move. The first field is the SalesAmtOnOrderLCY_3_.Value field, which is in the wrong location after the transformation. The second set of fields is three hidden fields that can cause problems in the printed layout of the report.

To update the layout

  1. In Visual Studio, on the last row of the table, right-click the field with the value =Sum(Fields!SalesAmtOnOrderLCY_3_.Value), and then click Cut.

  2. Right-click the empty field in the last row of the table that is between the =Sum(Fields!SalesAmtOnOrderLCY_2_.Value) and =Sum(Fields!SalesAmtOnOrderLCY_4_.Value) fields, and then click Paste.

  3. Expand the third row of the table.

  4. Decrease the width of the third column of the table.

  5. Select the three hidden fields on the third row of the table. These hidden fields are in the rightmost columns of the table. The values in the hidden fields are the following:

    • =Fields!COMPANYNAME.Value

    • =Fields!Customer__Order_SummaryCaption.Value

    • =Fields!CurrReport_PAGENOCaption.Value

  6. Right-click the three hidden fields, and then click Cut.

  7. Right-click the empty field in the first column of the second row of the table, and then click Paste to paste the three fields.

    Note Note

    We recommend that you move these hidden fields from the right of the table in all reports for which you create an RDLC report layout. Even though the fields are hidden, white space is still allocated on the page for the fields. In some cases, this causes problems with the print layout because of the width of the paper and the width of the table.

  8. Select the last three columns of the table from which you cut the hidden fields. Right-click the three columns, and then click Delete Columns.

The next step is to add detail lines and add data to those lines in the table so that the same information that was in the Classic client report layout is in the RDLC report layout.

To add data to detail lines

  1. Click in the table to make it active.

  2. Right-click the blank detail row, and then click Insert Row Below.

  3. Add the following values to the first blank detail line:

    • Customer_No_

    • Customer_Name

    • Leave the third column blank.

    • SalesAmtOnOrderLCY_1_Control31

    • SalesAmtOnOrderLCY_2_Control32

    • SalesAmtOnOrderLCY_3_Control33

    • SalesAmtOnOrderLCY_4_Control34

    • SalesAmtOnOrderLCY_5_Control35

    • SalesOrderAmountLCY_Control36

    To add these values, do the following:

    1. Right-click the field of the detail line, and then click Expression.

    2. In the Expression window, under Category, select Fields (DataSet_Result). Under Field, double-click the value from the previous list. An expression is added to the text box.

    3. For each amount value, the data that is shown must be the sum of the lines in the dataset. To create the sum, change the expression to Sum(<expression>). For example, change =Fields!SalesAmtOnOrderLCY_1_Control31.Value to =Sum(Fields!SalesAmtOnOrderLCY_1_Control31.Value)

    4. Click OK.

  4. For each value, you must modify the font and format. For each amount value, you must format the data by using the formatting that is given in the Classic client. To format the data, do the following:

    1. Right-click the field, and then click Properties.

    2. In the Textbox Properties window, click the Format tab.

    3. If the field is an amount field, under Format code, click the Expression button. In the Expression window, under Category, select Fields (DataSet_Result). Under Fields, select the Format value of the field that you selected. For example, select SalesAmtOnOrderLCY_1_Control31Format.

    4. Click OK.

    5. In the Textbox Properties window, click the Font tab.

    6. Under Size, enter 7pt.

  5. Add the following values to the second blank detail line:

    • Customer_No_

    • Customer_Name

    • Sales_Line__Currency_Code_

    • SalesAmtOnOrder_1_

    • SalesAmtOnOrder_2_

    • SalesAmtOnOrder_3_

    • SalesAmtOnOrder_4_

    • SalesAmtOnOrder_5_

    • SalesOrderAmount

    To add these values and format the fields, repeat steps 3 and 4 with the preceding fields.

  6. To get the sum of the lines in the dataset per customer, you must add a grouping property. To add the grouping property for each of the two detail rows that you added, do the following:

    1. Select the row.

    2. In the View menu, click Properties Window.

    3. In the Properties window, expand Data, and then select Grouping.

    4. In the Grouping and Sorting Properties window, in the Name field, enter Table1_Details_Group1.

    5. Under Group on, select a line to add an expression. From the drop-down list, select Fields!Customer_No_.Value, and then click OK.

  7. The request form for this report allows you to choose if the values should be displayed in local currency (LCY) or in the company's own currency. The first detail line that you added in step 3 shows the values in the local currency. The second detail line shows the values in the company's currency. To select which values will be printed in the report based on the selection in the request form, you must add a conditional statement to the visibility property. To set the visibility property, do the following:

    1. Select the first of the two rows that you added. This row has the LCY values. In the Properties window, expand Visibility. In the drop-down list for Hidden, select <Expression>.

    2. In the Expression window, change the expression to the following so that the row is hidden if Fields!PrintAmountsInLCY.Value is not true:

      = not first(Fields!PrintAmountsInLCY.Value)

    3. Select the second of the two rows that you added. This row does not have the LCY values. In the Properties window, expand Visibility. In the drop-down list for Hidden, select <Expression>.

    4. In the Expression window, change the expression to the following:

      =first(Fields!PrintAmountsInLCY.Value)

  8. To show the All Amounts are in LCY caption only when the values are displayed in local currency, do the following:

    1. Right-click the field =First(Fields!All_Amounts_are_in_LCYCaption.Value), and then select Properties.

    2. In the Textbox Properties window, click the Visibility tab.

    3. Under Initial visibility, select Expression, and then enter the following expression in the text box: =not First(Fields!PrintAmountsInLCY.Value)

    4. Click OK.

  9. To show the customer filter caption only when a customer filter is applied, do the following:

    1. Right-click the field =First(Fields!Customer_TABLECAPTION__________CustFilter.Value), and then click Properties.

    2. In the Textbox Properties window, click the Visibility tab.

    3. Under Initial visibility, select Expression, and then enter the following expression in the text box: =First(Fields!CustFilter.Value, "DataSet_Result")= ""

Expand image Saving the RDLC Report Layout

You must save the RDLC report layout, and you must also save and compile the changes in the Classic client.

To save the report

  1. In Visual Studio, on the File menu, click Save report.rdlc.

    Note Note

    If you close the report in Object Designer in the Classic client and then make changes in Visual Studio Report Designer and try to save the RDLC layout, you will get the Save As dialog box instead of the Save dialog box because the temporary Classic client file was removed.

  2. Close Visual Studio.

  3. In the Classic client, select an empty line in the report in Object Designer.. The following message appears:

    The layout of report id: '107' is changed by another application.

    Filename of the changed RDLC: <filename>

    Do you want to load the changes?

  4. Click Yes to load the changes that you made to the RDLC report layout into the Classic client.

  5. In the Classic client, on the File menu, click Save.

  6. In the Save window, select the Compiled check box, and then click OK.

  7. Close the report in Object Designer.

After you complete the preceding procedures, the layout of the report should look like the following illustration.

The report should look like the following illustration.

Expand image Transforming the Request Form

In addition to creating an RDLC report layout, you must transform the request form that allows you to select filters for the report. To do this, you use the form transformation tool.

To transform the request form

  1. Install the form transformation tool. For more information, see How to: Install the Form Transformation Tool.

  2. In the Classic client, on the Tools menu, click Object Designer.

  3. In Object Designer, click Report, and then select Report 107, Customer - Order Summary.

  4. On the File menu, click Export.

  5. In the Export Objects window, enter Report107_Forms.xml for the name of the file. Browse to the folder where the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file is located, and then click Save.

  6. Edit the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file.

    • Change the name of the Forms.xml file to Report107_Forms.xml.

      CopyCode image Copy Code
      <add key="FormsFile" value=".\Report107_Forms.xml" />

    • Change the name of the output pages.xml file to Report107_Pages.xml.

      CopyCode image Copy Code
      <add key="PagesFile" value=".\Report107_Pages.xml" />

  7. Run the form transformation tool. For more information, see How to: Run the Form Transformation Tool.

  8. In the Classic client, click Tools, and then click Object Designer.

  9. On the File menu, click Import.

  10. In the Import Objects window, in the Files of type drop-down list, select XML Format (*.xml), browse to the folder where the Report107_Pages.xml file is located, select Report107_Pages.xml, and then click Open.

  11. In Object Designer, click Report, and select report 107.

  12. On the Tools menu, click Compile, and then click Yes.

  13. To view the RDLC report layout, type the following command at a command prompt:

    DynamicsNAV:////runreport?report=107


Troubleshooting: Classic Client Report Designer and Visual Studio Report Designer

Troubleshooting: Classic Client Report Designer and Visual Studio Report Designer
See Also

You cannot open Visual Studio Report Designer and get the following error:

The provided metadata is not valid.

This error can happen when the following conditions are true:

  • You are using Windows Vista and User Access Control (UAC) is turned on.

  • The executable file that runs the Visual Studio development environment (devenv.exe) is set to run as an administrator.

  • The executable file that runs the Classic client with Microsoft SQL Server (finsql.exe) is not set to run as an administrator.

To resolve this issue, set both finsql.exe and devenv.exe to run as an administrator.

To set a program to run as an administrator

  1. Right-click the .exe file, and then select Properties.

  2. In the Properties window, on the Compatibility tab, in the Privilege Level section, select Run this program as an administrator.

See Also

Tasks

How to: Integrate Classic Client Report Designer and Visual Studio Report Designer


Developing Codeunits

A codeunit is a container for C/AL code that you can use in many application objects. This section describes codeunits and explains how to create one. It also shows you how to use the functions in a codeunit from other application objects.

Understanding Codeunits

To | See
Learn the purpose and function of codeunits | Understanding C/SIDE Codeunits
Learn about using the C/AL Editor | Creating and Modifying Codeunits
Learn about accessing codeunits and limitations of codeunits | Using Codeunits
Follow step-by-step procedures that show how to use codeunits | Walkthrough: Using Codeunits

Developing Codeunits

To | See
Learn how to create a codeunit | How to: Create a Codeunit
Learn how to modify a codeunit | How to: Modify an Existing Codeunit and How to: Add a Function to a Codeunit
Learn how to compile and save codeunits | How to: Compile the Code in a Codeunit and How to: Save a Codeunit


Understanding C/SIDE Codeunits

Understanding C/SIDE Codeunits

A codeunit is a container for C/AL code that you can use in many application objects. In simple applications, you can place the code in the object that calls the functions. For example, if you use C/AL code in forms, you can store the code in the form. However, as your application grows in both size and complexity, you will often find that you use the same functions more than once in many different objects. Instead of declaring the same functions repeatedly, you can use a codeunit to define them once.

What You Can Define in Codeunits

In codeunits, you can define the following:

  • Functions A function is a sequence of C/AL statements that you define to create new functionality.

  • Local Variables Within each function you can define variables whose scope is limited to the function in which they are defined. These are known as local variables.

  • Global Variables A global variable is a variable whose scope covers all the functions in the codeunit.

  • Temporary Tables A temporary table is a table that is not stored in the database. Temporary tables are used mainly as structured variables that hold data temporarily while you work on it.

Codeunit Sections

Each function that you add to a codeunit is shown in a separate section when you view the file in the C/AL Editor. Every codeunit contains two default sections called Documentation and OnRun. In the Documentation section, you can add descriptive information, such as the purpose of the codeunit or a version number. In the OnRun section, you can include code that you want to be executed when the codeunit is run.

In addition to being a container for functions that can be run individually, a codeunit can itself be run by using <Codeunitname>.Run. When you run a codeunit, the code in the OnRun section of the codeunit is executed.


Creating and Modifying Codeunits

Creating and Modifying Codeunits

You use Object Designer to create a new codeunit and you use the C/AL Editor to modify an existing codeunit.

For more information about how to create a codeunit, see How to: Create a Codeunit. For more information about how to modify a codeunit, see How to: Modify an Existing Codeunit.

Using the C/AL Editor

The C/AL Editor makes it easy to create and modify C/AL code. When you are working in the C/AL Editor, you have access to the C/AL Symbol Menu that helps you define C/AL functions. From the C/AL Symbol Menu, you can get help about all the C/AL commands. To view help for a function, select the C/AL function name in the right column and press F1.

You can open as many codeunits as you like. Each time you create a new codeunit or open an existing one, it is displayed in a separate window. This makes it easy to cut and paste lines of code between the codeunits. You can access the editing functions (Cut, Copy, and Paste) either from the Edit menu or by using the buttons on the toolbar. You can also use the standard shortcut keys that are described in the following table.

Shortcut key | Description
CTRL+X | Cuts the selected text to the clipboard.
CTRL+C | Copies the selected text to the clipboard.
CTRL+V | Pastes the text on the clipboard into the codeunit at the cursor position.
CTRL+F | Opens the Find window to search for text.

Defining Variables, Text Constants, and Functions

After you create a new codeunit, the next step is to define the global variables, text constants, and functions that you need in the codeunit. You use the C/AL Globals tool for this. To access the C/AL Globals tool, select the C/AL Editor, click View, and then click C/AL Globals. In the C/AL Globals window, you must decide whether you want to add a global variable, a text constant, or a function. For more information, see the following topics:

  • How to: Add a Global Variable to a Codeunit

  • How to: Add a Text Constant to a Codeunit

  • How to: Add a Function to a Codeunit

Using the C/AL Symbol Menu

When you write C/AL code in the C/AL Editor, you can use the C/AL Symbol Menu window to get an overview of the following:

  • All the variables defined in the codeunit

  • All the C/AL functions

The C/AL Symbol Menu is divided into the following columns:

  • The first column lists the names of the variables (if you have defined any) and the function categories.

  • The second column lists the subcategories.

  • The third column lists the functions in the category that you selected.

You can see the syntax and other information, such as the Caption property corresponding to the field name that you have selected, in the lower left corner of the window.

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 in the C/AL Symbol Menu.

In the C/AL Symbol Menu, click OK or Apply to paste the syntax description into the C/AL Editor. When you click OK, the C/AL Symbol Menu window is closed automatically. When you click Apply, the window stays open.

For more information, see C/AL Functions.

Compiling and Saving Codeunits

Before you can run the functions in a codeunit, you must save and compile the code. When you compile the code, the syntax of the statements are checked. If the compiler finds any errors in the code it displays an error message. For more information about how to compile the code in a codeunit, see How to: Compile the Code in a Codeunit. For more information about how to save a codeunit, see How to: Save a Codeunit.


How to: Create a Codeunit

How to: Create a Codeunit

To create a new codeunit by using Object Designer, use the following procedure.

To create a codeunit

  1. Click the Tools menu and then click Object Designer.

  2. In Object Designer, click Codeunit.

  3. Click New to create a new codeunit.

  4. In the C/AL Editor, add functions.

See Also

Concepts

Developing Codeunits


How to: Modify an Existing Codeunit

How to: Modify an Existing Codeunit

To modify an existing codeunit, use the following procedure.

To modify an existing codeunit

  1. In the Tools menu, click Object Designer.

  2. In Object Designer, click Codeunit.

  3. Select the codeunit that you want to modify, and then click Design.

  4. In the C/AL Editor, modify the codeunit by changing the existing functions or by adding new functions.

See Also

Concepts

Developing Codeunits


How to: Add a Global Variable to a Codeunit

How to: Add a Global Variable to a Codeunit

To add a global variable to a codeunit, use the following procedure.

To add a global variable

  1. Select the C/AL Editor, click View, and then click C/AL Globals.

    Note Note

    For more information about how to open the C/AL Editor, see How to: Modify an Existing Codeunit.

  2. In the C/AL Globals window, click the Variables tab.

  3. Enter a name and select a data type.

    If the data type that you select corresponds to an application object, you must also select a subtype, that is, the name of a specific object in the database.

    If you select OCX or Automation, you must add a subtype. For more information, see Extending Microsoft Dynamics NAV Using COM.

    If you select text or code, you must define a length for the variable. The default length is 10 characters for code and 30 characters for text.

See Also

Concepts

Developing Codeunits


How to: Add a Text Constant to a Codeunit

How to: Add a Text Constant to a Codeunit
See Also Example

To add a text constant to a codeunit, use the following procedure.

To add a text constant

  1. Select the C/AL Editor, click View, and then click C/AL Globals.

    Note Note

    For more information about how to open the C/AL Editor, see How to: Modify an Existing Codeunit.

  2. In the C/AL Globals window, click the Text Constants tab.

  3. In the first available Name field, enter the name of the new text constant.

    Note Note

    There is no naming convention for the text constants. We recommend that you use the unique ID for the name, as described in steps 4 and 5.

  4. Select the line in which you entered the name of the new text constant, click the View menu, and then click Properties. A unique ID number has been automatically assigned to the text constant in the ID field.

  5. Copy the ID number from the Properties window to the Name field in the C/AL Globals window. For example, if the ID number is 1001, specify Text1001, in the Name field.

  6. In the ConstValue field, click the AssistButton (…).

  7. In the Multilanguage Editor window, enter ENU for the language and then enter the text. For more information, see How to: Enter Text in the Multilanguage Editor

    Note Note

    If you set the application language to English (United States) before opening Object Designer, you can enter the message string directly into the ConstValue field in the C/AL Globals window. Open the Multilanguage Editor to be sure that the text is saved as English (United States).

  8. In the C/AL Editor, copy the name of the text constant to the place where you want the text value to appear.

Example

In this example, Text1001 is a number that is available in the text constants number series for that object.
CopyCode image Copy Code
IF FileName = ' ' THEN
ERROR(Text1001);

In the C/AL Editor, when you move the cursor into the new text constant, you see its contents in the status bar.

See Also

Concepts

Developing Codeunits


How to: Add a Function to a Codeunit

How to: Add a Function to a Codeunit

To add a function to a codeunit, use the following procedure.

To add a function

  1. Select the C/AL Editor, click View, and then click C/AL Globals.

    Note Note

    For more information about how to open the C/AL Editor, see How to: Modify an Existing Codeunit.

  2. In the C/AL Globals window, click the Functions tab.

  3. Enter a name for each function that you want to add.

  4. Click Locals to define the parameters, return value, local variables, and text constants in the C/AL Locals window.

  5. In the C/AL Locals window, click the Parameters tab and specify the calling method, name, and data type of each parameter. You can also specify a subtype and a length, but this is optional.

    To specify the calling method of a parameter, either select or clear the Var check box. If you select the Var check box, then 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. When the parameter is not specified as Var, only a copy of the variable is passed to the function. If the function changes that value, the change only affects the copy and not the variable itself.

    If the type that you select corresponds to an application object, then you must also add a subtype, that is, the name of a specific object in the database. If you select Text or Code data types, then you must define a length. The default length is 10 characters for Code and 30 characters for Text.

  6. In the C/AL Locals window, click the Return Value tab and specify the return value for your new function. Enter a name for the return value and select a data type from the drop-down list. If the data type is Text or Code, then you can also select a length.

  7. In the C/AL Locals window, click the Variables tab and define local variables.

    For each local variable, you must enter a name and select a data type. If the data type that you select corresponds to an application object, then you must also add a subtype, that is, the name of a specific object in the database. If you select Text or Code data types, then you must define a length for the variable. The default length is 10 characters for Code and 30 characters for Text.

  8. In the C/AL Locals window, click the Text Constants tab and define text constants for the function.

See Also

Concepts

Developing Codeunits


How to: Compile the Code in a Codeunit

How to: Compile the Code in a Codeunit

To compile the code in a codeunit, use the following procedure.

To compile the code in a codeunit

  1. Click the Tools menu and then click Compile.

  2. If any errors are found in your code, you receive an error message. Correct the errors and compile the code again.

See Also

Concepts

Developing Codeunits


How to: Save a Codeunit

How to: Save a Codeunit

To save a codeunit, use the following procedure.

To save a codeunit

  1. Select the C/AL Editor, click the File menu, and then click Save As.

  2. In the Save As window, in the ID field, enter an ID number that is used as a unique identification. In the Name field, enter a name that is used as a label.

  3. In the Save As window, click OK.

  4. In the dialog box, select whether you want to compile the code before it is saved. If you save the codeunit without compiling it, you will not be able to run it or call any of the functions it contains.

    Note Note

    If you are working on a large and complicated codeunit, you may want to save your work at regular intervals, even though it is not yet finished and cannot yet be compiled. In this case, you must clear the Compiled check box before you save the codeunit.

See Also

Concepts

Developing Codeunits


Using Codeunits

Using Codeunits

By using codeunits, you eliminate the need to duplicate code and you make the code easier to maintain. If you use the same code repeatedly in your forms or reports, you should create a function in a codeunit. After you create a function in a codeunit you can access it by using <CodeunitName>.<FunctionName>.

Example

For this example, assume that you have created a codeunit that contains two statistical functions named F and G. The following example shows you how to access these functions from a form.

Codeunit named StatFun

CopyCode image Copy Code
F(x:integer)
Begin
…
End

G(x:integer)
Begin
…
End

Any Form

CopyCode image Copy Code
…
Result := StatFun.F(3425)+StatFun.G(346);
…

Accessing Codeunits

Using the method in the preceding, from any application object, you can access functions in other application objects by writing the name of the application object that contains the function followed by the name of the function.

You can access codeunits through codeunit variables either by explicitly declaring a variable with the data type codeunit or by setting the RunObject property on forms 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.

Codeunit Variables

Codeunits contain internal variables that are defined as global variables. These variables cannot be accessed directly from code outside the codeunit, but they can be accessed through user-defined functions on the codeunit. When 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.

CLEAR on Codeunits

When you use the CLEAR function on a codeunit variable that has a reference to a codeunit instance with two or more references, CLEAR only deletes the reference to the codeunit and not the actual instance of the codeunit. The codeunit stays intact and can still be used by other codeunit variables that may have been assigned a reference to this codeunit.

To delete an instance of a codeunit, you must clear all the references to the codeunit with the CLEAR function. To clear the internal variables in a codeunit, you must call the CLEARALL function from a user-defined function within the codeunit. A local codeunit variable is automatically cleared when it goes out of scope and is no longer used by the codeunit.

For more information about, see the following topics:

  • CLEAR Function

  • CLEARALL Function

Single Instance Codeunit

In some cases, only one instance of a codeunit needs to exist. This means that all the codeunit variables of a particular codeunit use the same set of variables. When you set the SingleInstance property of the codeunit to Yes, all the codeunit variables of that codeunit use the same instance, thereby allowing you to create global variables.

Note Note

We recommended that you avoid using global variables for most types of code. However, in certain situations, it may be necessary to use them, for example, to ensure that you are only using one instance of an external variable.

A single instance codeunit is instantiated when you use it for the first time. Normal codeunit instances (codeunits that do not have the SingleInstance property set) are deleted when the last codeunit variable that uses that codeunit instance goes out of scope. However, single instance codeunits remain instantiated until you close the company.

For an example of a single instance codeunit, see Walkthrough: Using Codeunits.

Limitations on Codeunits

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 the functions that you have created in the codeunit.

Every C/AL function can be used in a codeunit. However, you cannot create a function with the same name as a pre-defined function. Also, two or more user-defined functions cannot have the same name, unless they are part of different application objects.


Walkthrough: Using Codeunits

Walkthrough: Using Codeunits

You can treat codeunits as objects. One codeunit variable can be assigned to another codeunit variable, which creates a new reference to the same codeunit instance. The codeunit variables then use the same set of internal variables.

Expand image About This Walkthrough

This walkthough illustrates the following tasks:

  • Creating one codeunit that has two functions: Set and Get. Set sets an internal variable to the value of the parameter given. Get returns the value of the internal variable.

  • Creating one codeunit that has two variables that call the first codeunit and are then assigned to each other so that they use the same instance of the first codeunit.

  • Modifying one of these codeunits to make it a single instance codeunit.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license

  • The CRONUS International Ltd. demo data company installed

Expand image Story

Viktor is a Microsoft Certified Partner working for CRONUS International. To learn about codeunits in Microsoft Dynamics NAV, he plans to create some codeunits and use variables in those codeunits in different ways.

Expand image Creating the First Codeunit

First, you must create a codeunit that includes the Set and Get functions. You must also write the code for these two functions.

To create the first codeunit

  1. In the Classic client, click the Tools menu, and then click Object Designer.

  2. In Object Designer, click Codeunit and then click New.

  3. In the View menu, click C/AL Globals.

  4. On the Variables tab, in the Name field, enter InternalInt to create a new variable. In the DataType field, select Integer from the drop-down list.

  5. In the C/AL GLobals window, click the Functions tab.

  6. On the Functions tab, in the Name field, add two functions called Set and Get.

  7. Select the Set function and then click Locals.

  8. In the Set - C/AL Locals window, on the Parameters tab, in the Name field, enter input. In the DataType field, select Integer from the drop-down list.

  9. Close the Set - C/AL Locals window.

  10. In the C/AL GLobals window, select the Get function, and then click Locals.

  11. In the Get - C/AL Locals window, click the Return Value tab.

  12. In the Name field, enter out. In the Return Type field, select Integer from the drop-down list.

  13. Close the Get - C/AL Locals window.

  14. In the C/AL Editor for the codeunit, in the Set function section, enter the following code.

    CopyCode image Copy Code
    InternalInt := input + 1;
Get;

    The code in the Set function increases the value of the input by one and sets this as the value of the internal variable. It then calls the Get function.

  15. In the C/AL Editor, in the Get function section, enter the following code.

    CopyCode image Copy Code
    out := InternalInt;

    The code in the Get function specifies that the new value of the internal variable is the output value generated by this codeunit.

  16. Close the C/AL Editor. Click Yes to save your changes to the codeunit.

  17. In the Save As window, in the ID field, enter 70000. In the Name field, enter Set_Get. Select the Compile check box, and then click OK.

Expand image Creating the Second Codeunit

The next step is to create the codeunit that calls two instances of the Set_Get codeunit and supplies the input values that these instances should use. This codeunit contains two variables, which are assigned to each other so that they both use the same instance of codeunit 70000.

To create the second codeunit

  1. In Object Designer, click Codeunit, and then click New.

  2. In the View menu, select C/AL Globals.

  3. On the Variables tab, in the Name field, enter CoMIC1 to create a new variable. In the DataType field, select Codeunit from the drop-down list. In the Subtype field, select codeunit 70000, Set_Get.

  4. In the C/AL GLobals window, on the Variables tab, in the Name field, enter CoMIC2 to create a second variable. In the DataType field, select Codeunit from the drop-down list. In the Subtype field, select codeunit 70000, Set_Get.

  5. Close the C/AL GLobals window.

  6. In the C/AL Editor, add the following code to the OnRun trigger.

    CopyCode image Copy Code
    CoMIC1.Set(1);
CoMIC2.Set(2);
// Calls two instances of codeunit 70000
// with the input parameters 1 and 2, respectively.
MESSAGE('When running two instances, the value of CoMIC1 is %1 and the value of CoMIC2 is %2.',CoMIC1.Get,CoMIC2.Get);
// The message retrieves the return values from codeunit 70000
// and shows them in the message.
// CoMIC2 returns 2.
// ComIC2 returns 3, because you have added 1 to each parameter.
CoMIC2 := CoMIC1;
// CoMIC2 is assigned to CoMIC1
// and they both use the same instance of codeunit 70000.
MESSAGE('After assinging CoMIC2 to CoMIC1, the value of CoMIC1 is %1 and the value of CoMIC2 is also %2.',CoMIC1.Get,CoMIC2.Get);
// CoMIC1 and CoMIC2 now show the same value.

    The first statement in this codeunit calls two instances of the Set_Get codeunit and supplies the input values that these instances should use. The next statement assigns the two variables to each other so that they both use the same instance of codeunit 70000 and therefore generate the same return value.

  7. Close the C/AL Editor. Click Yes to save your changes to the codeunit.

  8. In the Save As window, in the ID field, enter 70001. In the Name field, enter Assignment. Select the Compile check box, and then click OK.

Expand image Using a Single Instance Codeunit

In some cases, only one instance of a codeunit needs to exist. This means that all the codeunit variables of a particular codeunit use the same set of variables. You can make a codeunit a single instance codeunit by setting the SingleInstance property to Yes.

To modify a codeunit to a single instance codeunit

  1. In Object Designer, click Codeunit, select codeunit 70000, and then click Design.

  2. In the View menu, click Properties.

  3. In the Properties window, in the SingleInstance field, select Yes from the drop-down list.

  4. Close the Set_Get - Properties window.

  5. In the File menu, click Save As.

  6. In the Save As window, in the ID field, enter 70002. In the Name field, enter SingleInst. Select the Compile check box, and then click OK.

  7. In Object Designer, click Codeunit, select codeunit 70000, and then click Design.

  8. In the View menu, select C/AL Globals.

  9. On the Variables tab, in the Name field, enter CoMIC1. In the DataType field, select Codeunit from the drop-down list. In the Subtype field, select codeunit 70002, SingleInst.

  10. On the Variables tab, in the Name field, enter CoMIC2. In the DataType field, select Codeunit from the drop-down list. In the Subtype field, select codeunit 70002, SingleInst.

  11. Close the C/AL Globals window.

  12. In the C/AL Editor, add the following code to codeunit 70000 to the OnRun trigger:

    CopyCode image Copy Code
    CoMIC1.Set(7);
// A codeunit instance is created if one did not exist.
CoMIC2.Get();
// Returns 8, that is 7 + the 1 added by the set function in
// codeunit 70002. CoMIC2 uses the same instance as CoMIC1,
// they use the same internal variables.
MESSAGE('the value of CoMIC2 is %1',CoMIC2.Get);

  13. Close the C/AL Editor. In the Save Changes window, select the Compiled check box, and then click Yes to save your changes.

  14. In Object Designer, select codeunit 70000, and then click Run. The following message appears, "The value of CoMIC2 is 8"

    The input value in codeunit 70000 is 7 and codeunit 70002 adds 1 to this value.

  15. In Object Designer, select codeunit 70002, and then click Design.

  16. In the Set function, change the first line to the following.

    InternalInt := input+4.

  17. Close the C/AL Editor. In the Save Changes, window, select the Compiled check box, and then click Yes to save your changes.

  18. In Object Designer, select codeunit 70000, and then click Run. You will get the same message that you received in step 14. This occurs because after you have loaded a single instance codeunit, it remains loaded on the client until you restart the client.

    Note Note

    It is possible to use a single instance codeunit across objects, not just within the same object.

Expand image See Also

Concepts

Using Codeunits


Creating Dataports

Creating Dataports

Dataports are similar to XMLports as they are object types that can import and export data. The difference is that the data is encapsulated in text files. This makes it possible to exchange information between different computing systems where XML is not supported. For example, you can use dataports to export data, modify the data in an external program such as Microsoft Office Excel, and then import the modified data into the Microsoft Dynamics NAV database.

Note Note

Application Server for Microsoft Dynamics NAV does not support dataports.

Deciding Between Dataports and XMLports

There are two reasons to use dataports to export data from Microsoft Dynamics NAV or import data into Microsoft Dynamics NAV:

  • To support businesses that use previous versions of Microsoft Dynamics NAV, and therefore work with dataports rather than XMLports.

  • To modify Microsoft Dynamics NAV data in a tool that does not support XML.

Introducing Dataports

To | See
Learn about dataports. | Dataport Fundamentals
Read the principles of designing dataports. | Designing Dataports
Learn how to create a dataport. | Walkthrough: Creating a Dynamic Dataport

See Also

Concepts

Creating XMLports


Dataport Fundamentals

Dataport Fundamentals

Dataports enable you to import data from external text files to the Microsoft Dynamics NAV database and export data from the Microsoft Dynamics NAV database to text files in cases where XML is not supported. For all other cases, use XMLports instead. For more information, see Creating XMLports.

A dataport is an object. There is a wide range of options for defining the format of the external file while you are importing and exporting the object. You design dataports in Dataport Designer, which you open from Object Designer.

Note Note

Application Server for Microsoft Dynamics NAV does not support dataports.

Defining Dataports

A dataport object defines the data that must be exported from or imported into the Microsoft Dynamics NAV database. When you are importing data, you can control what happens if a record in the file being imported has the same value in the key as an existing record in the database table. In addition, at field level, you can control if the OnValidate trigger for each field should be run.

Dataports can be dynamic, meaning that when you execute the dataport, you specify if it must import or export data, and you specify the name of the file to read from or write to. This can be achieved either by defining options that the user sets in the request form or by programming.

Dataports can be run without user interaction.

Logical Design

Designing a dataport involves two distinct tasks:

  • Designing the data model.

  • Defining the layout of the external file.

Designing the Data Model

You build the data model by designing data items. A data item corresponds to a table.

When you are exporting data, each data item is iterated for all the records in the underlying table, and you can set up sort order, keys, and table views to use. You can decide whether each record should be written to the external file.

When you are importing data, the records read from the external file can be inserted into tables that correspond to the data items. You can examine the records before inserting them and you can specify:

  • If the records should be inserted.

  • If the records should be inserted automatically.

  • If the records that are already in the database should be overwritten or updated when a record with the same primary key is read from the external file.

For more information, see Designing Dataports.

Designing the External File

The layout of the external file is defined by means of a set of dataport properties. When you are importing, these properties describe how the input stream should be broken up into records and fields. When you are exporting, these properties describe how the fields and records should be written to the file.

The properties that you can set vary depending on the format of the external file.

For more information, see Designing Dataports.

Saving, Compiling, and Running a Dataport

After you have designed a dataport, you must save and compile it before it can be run. Usually, you do this when you have finished designing the dataport. However, you may want to save a dataport that is not yet finished and therefore cannot be compiled. For more information, see How to: Save a Dataport. You can also test-compile a dataport without closing or saving it. For more information, see How to: Compile a Dataport.

Running Dataports

When a dataport runs, various triggers execute C/AL functions. The following illustration shows the flow of running a dataport.

The following list describes the steps needed to run a dataport.

  1. When you start the dataport run, the OnInitDataport trigger is run.

    Note Note

    Use this trigger to initialize variables but not for general processing purposes.

  2. When the OnInitDataport trigger has been executed, the request form for the dataport is run, if it is defined. You can cancel the dataport run from the request form.

  3. If you choose to continue, the dataport enters a transaction by issuing a Begin Write Transaction (BWT), and then the OnPreDataport trigger is called. No data has been processed at this stage.

  4. The OnPreDataport trigger can be used to process the user input from the request form.

  5. When the OnPreDataport trigger has been executed, the external file is opened, and the processing of the first data item begins.

  6. When the first data item has been processed, the next data item, if there is one, is processed in the same way.

  7. When there are no more data items, the OnPostDataport trigger is called. You can use this trigger to do any post processing that is necessary.

  8. When the OnPostDataport has been processed, the external file is closed.

  9. The transaction that was entered in step 3 ends with an End Write Transaction (EWT) being issued.

The processing of each data item (steps 5 and 6) is, of course, different for importing and exporting. However, the entire processing of a dataport takes place within a transaction. This means that if the processing is interrupted before the final EWT is issued, no trace is left of the interrupted run in the database, but an external file will often have been corrupted.

See Also

Tasks

How to: Create a Dataport for Exporting Data
How to: Create a Dataport for Importing Data
How to: Save a Dataport
How to: Compile a Dataport

Concepts

Creating Dataports
Designing Dataports


Designing Dataports

Designing Dataports

Designing a dataport consists primarily of setting various properties. The following sections explain which properties to use, and how to use them.

For an example of how to define dataports, see Walkthrough: Creating a Dynamic Dataport.

Dataport Design

The following table lists the components of a dataport object.

Dataport component Description

Dataport description

A complete description of the dataport including how data is collected, how data is formatted when written to the output file, and so on. The dataport description is stored in the database.

Data item

A data item corresponds to a table in the database. You define data items so that you can retrieve information from the tables in the database. A dataport must contain at least one data item, and each data item defines one or more fields.

Field

A dataport field can be a field in a data item (a database table), a field in a file from which data is to be imported, or a source expression to be executed during import or export. Fields in the external file are defined either as having a fixed length, or as being delimited by certain characters that you define.

Request form

A request form is a form that is run before the dataport is executed. The request form is used to gather requests and options from the user, for example, the name and location of the external file.

Note Note

Dataports can be run without user interaction. In that case, the C/AL code that calls the dataport must provide any required information, such as the name and location of the external file.

Property

The dataport itself, and data items, fields, and the request form have properties that characterize the object in some way. For example, the length and position of a field in a line during import, or whether the OnValidate trigger of a field should be executed when inserting imported data into a table. Properties are set in the Properties window of an object during design time. Also, the request form for a dataport contains fields that set properties on the dataport and its data items.

Trigger

Certain predefined events that happen to a dataport cause the system to execute a user-defined C/AL function—the event triggers the function. Triggers are available for the dataport itself, the data items, the fields, the request form, and the controls on the request form. You can edit triggers in the C/AL editor. For more information, see Triggers on Dataports Overview.

Defining File Formats

The file format you set for a dataport determines which properties are available for that dataport. For example, if you set the file format to Variable, the FieldEndDelimiter, FieldStartDelimiter, and FieldSeparator properties become active. For more information, see Properties for a Dataport.

The FileFormat property determines the format of the external file and defines how a record is read from or written to the file. The RecordSeparator property defines how the file is broken into records, and the FileFormat property then defines how to break each record into fields. Finally, the DataItemSeparator property defines how data items should be separated if the dataport has more than one data item.

Note Note

Data items cannot be nested, although a dataport can have several data items that are processed sequentially.

Defining Fields in Records

When the format of the external file is Fixed, the fields in a record have a fixed width. You can define the starting position and the width of each field in the record. If the record separator is a new line character, a record is essentially a line of text. For more information, see Properties for a Field on a Dataport Data Item.

When the format of the external file is Variable, the fields in a record are delimited by characters that you define, and the fields can have varying widths. The fields are separated by the string defined as the FieldSeparator property. For more information, see Properties for a Field on a Dataport Data Item.

See Also

Tasks

How to: Create a Dataport for Exporting Data
How to: Create a Dataport for Importing Data
How to: Save a Dataport
How to: Compile a Dataport
How to: Run a Dataport from Object Designer
Walkthrough: Creating a Dynamic Dataport

Reference

Properties for a Dataport
Properties for a Data Item in a Dataport
Properties for a Field on a Dataport Data Item

Concepts

Triggers on Dataports Overview
Dataport Fundamentals


How to: Create a Dataport for Exporting Data

How to: Create a Dataport for Exporting Data
See Also Example

In Microsoft Dynamics NAV, dataports can be set to export data to an external file with a fixed format or a variable format. This topic describes how to create a dataport for exporting data to an external file.

To create a dataport

  1. Click Tools, and then click Object Designer.

  2. In Object Designer, click Dataport, and then click New.

  3. Click an empty line in Dataport Designer to select the dataport itself, click View, and then click Properties.

    This opens the Properties window of the dataport. Alternatively, click Edit, click Select Object, and then open the Properties window.

  4. In the Properties window for the new dataport, set the following properties.

    Property Value

    Import

    No

    FileFormat

    Fixed

  5. In Dataport Designer, in the first DataItem field, click the AssistButton, and then select the table that you want to add to the dataport. For example, to export data from the G/L Account table, select table 15.

    The name is set by default to the name of the table. Optionally, you can change this.

You have created a dataport with a single data item and must now specify which fields from the underlying table will be used in the dataport.

To add fields to a data item

  1. In Dataport Designer, select the data item that you want to add fields to.

  2. Click View, and then click Dataport Fields.

  3. In the Field Designer window, in the SourceExpr field, add the first field to the data item.

    This can be a field in the table that the data item corresponds to, or it can be a source expression that maps to a field in another table. For example, if the field is the No. field on the current table, the value of the SourceExpr field is "No.". If the field is on another table, such as the Description field in the Tariff Number table, the value of the SourceExpr field can be "Tariff Number".Description, where Tariff Number is a global variable for the Tariff Number table.

    Alternatively, you can use the field menu to add multiple fields from the current table.

    1. When the Field Designer window is open, click View, and then click Field Menu.

    2. In the Field Menu window, select the fields that you want to export.

      For example, from the field menu for the G/L Account data item, select the No., Name, Balance at Date, and Net Change fields.

    3. Click the Field Designer window, and then, in the dialog box that appears, click Yes to add the fields to the data item.

  4. In Field Designer, set the appropriate values for the StartPos and Width properties. For more information, see Properties for a Field on a Dataport Data Item.

    For fields on the current table that are not FlowFields, the StartPos and Width properties are automatically set for the fields.

  5. If the data item contains calculated fields, you must set the data item to calculate these values.

    1. In Dataport Designer, select the data item, click View, and then click Properties.

    2. In the Properties window for the data item, in the CalcFields property, click the AssistButton to open the Field List window.

    3. In the Field List window, select the fields from the data item that must be calculated when they are exported, that is, the FlowFields, and then click OK.

      For example, for fields in the G/L Account data item, select the Balance at Date and Net Change fields.

When you have specified the fields, you can finalize and test the dataport.

To finalize and run the dataport

  1. Optionally, for each data item, set values for key, sort order, and any table filters to remove the data item from the request form. This is required if the dataport runs without a user interface. For more information, see How to: Change the Request Form for a Dataport.

  2. Optionally, change the format of the external file. For example, you can change the formatting of field values. For more information, see How to: Change the File Format for a Dataport.

  3. Optionally, save the dataport before running it. For more information, see How to: Save a Dataport.

  4. Click File, and then click Run to run the dataport.

    When you run the dataport, the request form appears.

  5. In the request form, on the Options tab, in the File Name field, enter the location and the name of the file that the data will be exported to.

  6. Optionally, on the tab for the data item, set filters to specify which data to export.

  7. To run the dataport, click OK.

When the dataport run is finished, you can open the file in a text editor. For an example of the result of running a dataport, see the Example section.

Exporting with Variable Format

The preceding sections describe how to set a dataport to export data to an external file in a fixed format. However, you can also export data with variable format.

To export data with variable format

  1. Create a dataport as described in the first procedure. However, in the Properties window for the new dataport, set the following properties.

    Property Value

    Import

    No

    FileFormat

    Variable

    FieldSeparator

    ;

    FieldStartDelimiter

    <None>

    FieldEndDelimiter

    <None>

    FieldSeparator is set to use semicolon because the fields include both space characters and commas. Another solution would be to use the delimiters. In that case, FieldSeparator could also be a comma, but what you choose should really depend upon the target application for the exported file and the formats that the application supports when it imports text files.

  2. Optionally, change the default values of the RecordSeparator and the DataItemSeparator properties. If you use the default values, records will be separated by new lines, and data items by two new lines. This can be useful if your dataport includes several data items.

  3. Add the fields from the underlying table as described in the second procedure.

  4. When you have completed defining the dataport, save and run it. The result is an external file where the values of each field are separated by semicolons. The following example illustrates the output.

    CopyCode image Copy Code
    1000;BALANCE SHEET;0;0
1002;ASSETS;0;0
1003;Fixed Assets;0;0
1005;Tangible Fixed Assets;0;0
1100;Land and Buildings;0;0
1110;Land and Buildings;1.479.480,6;1.479.480,6
1120;Increases during the Year;147,73;147,73
1130;Decreases during the Year;0;0

Example

The following example illustrates the data that is exported if you run a dataport with a fixed file format, which contains a single data item for the G/L Account table.
CopyCode image Copy Code
1000                 BALANCE SHEET                  0            0
1002                 ASSETS                         0            0
1003                 Fixed Assets                   0            0
1005                 Tangible Fixed Assets          0            0
1100                 Land and Buildings             0            0
1110                 Land and Buildings             1.479.480,6  1479
1120                 Increases during the Year      147,73       0
1130                 Decreases during the Year      0            0
1140                 Accum. Depreciation, Buildings -526.620,38  -527
1190                 Land and Buildings, Total      953.007,95   953
1200                 Operating Equipment            0            0
1210                 Operating Equipment            582.872,18   583
1220                 Increases during the Year      25.116       25
1230                 Decreases during the Year      0            0
1240                 Accum. Depr., Oper. Equip.     -508.176,74  -508
1290                 Operating Equipment, Total     99.811,44    100
1300                 Vehicles                       0            0
1310                 Vehicles                       49.473,91    49
1320                 Increases during the Year      87.000       87
1330                 Decreases during the Year      0            0
1340                 Accum. Depreciation, Vehicles  -60.603,78   -61
1390                 Vehicles, Total                75.870,13    76
1395                 Tangible Fixed Assets, Total   1.128.689,52 1129
1999                 Fixed Assets, Total            1.128.689,52 1129

In the example, the data is exported from the Microsoft Dynamics NAV demo database. A filter has been applied to only export records where the value of the No. field is less than 2000. Also, the source expression for the Net Change field has been changed to FORMAT(ROUND("Net Change "/1000,1,'='),0,1) to export the values of this field as thousands, but the source expression for the Balance at Date field remains unformatted and returns data that is not rounded.

See Also

Tasks

How to: Save a Dataport
How to: Run a Dataport from Object Designer
How to: Create a Dataport for Importing Data
Walkthrough: Creating a Dynamic Dataport
How to: Change the Request Form for a Dataport
How to: Change the File Format for a Dataport

Concepts

Designing Dataports
Dataport Fundamentals


How to: Create a Dataport for Importing Data

How to: Create a Dataport for Importing Data

In Microsoft Dynamics NAV, you can set dataports to import data from an external file with a fixed format or a variable format. This topic describes how to create a dataport for importing data from an external file.

Creating a dataport that imports data is not very different from creating one that exports data. However, you must consider how the imported records are inserted in the database table on which the data item is based. This is especially relevant if the table already contains records that have the same primary key as some of the records that will be imported.

To create a dataport

  1. On the Tools menu, click Object Designer.

  2. In Object Designer, click Dataport, and then click New.

  3. In the Properties window for the new dataport, set the following properties.

    Property Value

    Import

    Yes

    FileFormat

    Fixed

  4. In Dataport Designer, in the first DataItem field, click the AssistButton, and then select the table that you want to add to the dataport. This is the table that the data will be imported into. For example, to import data into the Item table, select table 27.

    The name is set by default to the name of the table. Optionally, you can change this.

You have created a dataport with a single data item and must now specify which fields from the underlying table will be used in the dataport.

Note Note

You must know the number of fields per record in the external file, and you must know the position of each field.

To add fields to a data item

  1. In Dataport Designer, select the data item to which you want to add fields.

  2. On the View menu, click Dataport Fields.

  3. In Field Designer, in the SourceExpr field, add the first field to the data item.

    This can be a field in the table to which the data item corresponds, or it can be a source expression that maps to a field in another table. For example, if the field is the No. field on the current table, then the value of the SourceExpr field is "No.". If the field is on another table, such as the Description field in the Tariff Number table, then the value of the SourceExpr field can be "Tariff Number".Description, where Tariff Number is a global variable for the Tariff Number table.

    You can also use the field menu to add multiple fields from the current table.

    1. When Field Designer is open, on the View menu, click Field Menu.

    2. In the Field Menu window, select the fields to which you want to import.

      For example, from the field menu for the G/L Account data item, select the No., Name, Balance at Date, and Net Change fields.

    3. Click Field Designer, and then click Yes to add the fields to the data item.

  4. In Field Designer, set the appropriate values for the StartPos and Width properties. For more information, see Properties for a Field on a Dataport Data Item.

    For fields on the current table that are not FlowFields, the StartPos and Width properties are automatically set for the fields.

    Note Note

    Ensure that the values match the external file. If the fields have a different order in your table then they do in the file that you are importing, you can add the fields manually and ensure that the design of the data item reflects the order that you need. You must then set the StartPos and Width properties manually.

    If one of the fields is the primary key of the table, then the order in which the records are displayed is determined by the primary key, which may not be the same order as they appeared in the original import file.

When you have specified the fields, you can finalize and test the dataport.

To finalize and run the dataport

  1. Optionally, for each data item, set values for key, sort order, and any table filters to remove the data item from the request form. This is required if the dataport runs without a user interface. For more information, see How to: Change the Request Form for a Dataport.

  2. Optionally, save the dataport before running it. For more information, see How to: Save a Dataport.

  3. On the File menu, click Run to run the dataport.

    When you run the dataport, the request form appears.

  4. In the request form, on the Options tab, in the File Name field, enter the location and the name of the file from which the data will be imported.

  5. Optionally, on the tab for the data item, set filters to specify which data to import.

  6. To run the dataport, click OK.

When the dataport run is finished, the records in the Microsoft Dynamics NAV database are updated.

Note Important

The records are not imported if you run the dataport from inside Dataport Designer. You must run it from somewhere else, such as from Object Designer.

Importing with Variable Format

The preceding sections describe how to set a dataport to import data from an external file in a fixed format. However, you can also import data with variable format.

To import data with variable format

  1. Create a dataport as described in the first procedure. However, in the Properties window for the new dataport, set the following properties.

    Property Value

    Import

    Yes

    FileFormat

    Variable

    FieldSeparator

    ,

    FieldStartDelimiter

    <None>

    FieldEndDelimiter

    <None>

    FieldSeparator is set to use a semicolon because the fields include both space characters and commas. Another solution would be to use the delimiters. In that case, FieldSeparator could also be a comma, but what you choose should depend upon the target application for the external file and the formats that the application supports when it imports text files.

  2. Add the fields from the underlying table as described in the second procedure.

    Note Note

    The values of the StartPos and Width properties are not used in a dataport with a variable format. If the order of the fields in the import file is different from the order of the fields in the data item, then you must change the order of the fields in the data item by adding them manually in Field Designer.

  3. When you have completed defining the dataport, save and run it.

When you run the dataport, the result is the same as running the dataport with a fixed format.

Common Errors

It is easy to make errors when deciding how to parse the lines in the file that you are importing. In some cases, this will result in a run-time error when the dataport is run, such as if you make an error in setting up the Field No. field and assign it a width that is one character too wide. For most of the import file, this would make no difference because the resulting trailing space would be ignored. But in a line that starts with 112Oven, you would get a run-time error when C/SIDE reads 112O instead of 112. The letter O cannot be inserted into an integer field.

In other cases, the error might not be detected by C/SIDE, such as if the parse between two text fields is placed incorrectly. Always test your imports carefully before using them for production.

In some cases, the fields have a different order in your table than they do in the file that you are importing. You can add the fields manually and ensure that the design of the data item reflects the order that you need. You must set the StartPos and Width properties manually.

See Also

Tasks

How to: Change the Request Form for a Dataport
How to: Save a Dataport
How to: Run a Dataport from Object Designer
How to: Create a Dataport for Exporting Data
Walkthrough: Creating a Dynamic Dataport

Concepts

Designing Dataports
Dataport Fundamentals


How to: Change the Request Form for a Dataport

How to: Change the Request Form for a Dataport

The request form for a dataport contains a tab for each data item and an Options tab, where users can specify the name and location of the external file. If you do not want users to be able to change filters for a data item, or if the dataport will run without a user interface, you can change the request form to not include a tab for the data item. To remove a tab for a data item, you set values for key, sort order, or any table filters.

Caution note Caution

Even if you use the following procedure to set a value for only one of the properties, the data item tab will be removed from the request form.

To set values for a data item in Dataport Designer

  1. In Dataport Designer, select the data item, and then open the Properties window.

  2. In the Properties window, in the DataItemTableView property, click the AssistButton.

  3. In the Table View window, set values for the properties that you want to predefine. The following table illustrates the properties.

    Property Value

    Key

    The sorting key. For example, No. for the No. field.

    Order

    The sort order. For example, Ascending.

    Table Filter

    Filters to limit the data. For example, No.=FILTER(<2000).

  4. When you run the dataport, the request form will contain only the Options tab and tabs for any data items where you have not set values.

See Also

Tasks

How to: Create a Dataport for Exporting Data
How to: Change the File Format for a Dataport
How to: Save a Dataport
How to: Run a Dataport from Object Designer
How to: Create a Dataport for Importing Data
Walkthrough: Creating a Dynamic Dataport

Concepts

Designing Dataports
Dataport Fundamentals


How to: Change the File Format for a Dataport

How to: Change the File Format for a Dataport
See Also Example

In Dataport Designer, you can also change the format of the external file that the data is exported to. For example, you can change the format of the exported fields so that decimal numbers are not included or numbers are exported as thousands.

The following procedure illustrates how you use the SourceExpr property to export the decimal fields, Balance at Date and Net Change as thousands so that the number 1,444,723.67 is exported as 1444. These fields are used as an example because they are fields in the G/L Account table. For more information, see How to: Create a Dataport for Exporting Data.

To change field formats

  1. In Dataport Designer, select the data item, click View, and then click Dataport Fields.

  2. In the Field Designer window, select the field, such as Balance at Date, click View, and then click Properties.

  3. In the Properties window, in the SourceExpr property, type the relevant expression. For example, to export the value of a decimal field as thousands, type the following expression.

    CopyCode image Copy Code
    FORMAT(ROUND("field name"/1000,1,'='),0,1)

    This C/AL statement ensures that the value of the decimal field is divided by 1000. The result is rounded by the ROUND function, and then the FORMAT function is used to render the value returned by the ROUND in format 1. For a decimal value, this means <Sign><Integer><Decimals>. For more information, see ROUND Function (Decimal).

When you run the dataport, the data in the external file will reflect this formatting.

Example

The following example illustrates the data that is exported if you run a dataport with a fixed file format. This dataport contains a single data item for the G/L Account table, where the format of values in a decimal field has been changed.
CopyCode image Copy Code
1000                 BALANCE SHEET                  0            0
1002                 ASSETS                         0            0
1003                 Fixed Assets                   0            0
1005                 Tangible Fixed Assets          0            0
1100                 Land and Buildings             0            0
1110                 Land and Buildings             1,479,480.6  1479
1120                 Increases during the Year      147.73       0
1130                 Decreases during the Year      0            0
1140                 Accum. Depreciation, Buildings -526,620.38  -527
1190                 Land and Buildings, Total      953,007.95   953
1200                 Operating Equipment            0            0
1210                 Operating Equipment            582,872.18   583
1220                 Increases during the Year      25,116       25
1230                 Decreases during the Year      0            0
1240                 Accum. Depr., Oper. Equip.     -508,176.74  -508
1290                 Operating Equipment, Total     99,811.44    100
1300                 Vehicles                       0            0
1310                 Vehicles                       49,473.91    49
1320                 Increases during the Year      87,000       87
1330                 Decreases during the Year      0            0
1340                 Accum. Depreciation, Vehicles  -60,603.78   -61
1390                 Vehicles, Total                75,870.13    76
1395                 Tangible Fixed Assets, Total   1,128,689.52 1129
1999                 Fixed Assets, Total            1,128,689.52 1129

In the example, the data is exported from the Microsoft Dynamics NAV demo database. A filter has been applied to only export records where the value of the No. field is less than 2000. Also, the source expression for the Net Change field has been changed to FORMAT(ROUND("Net Change "/1000,1,'='),0,1) to export the values of this field as thousands, but the source expression for the Balance at Date field remains unformatted and returns data that is not rounded. For more information, see How to: Create a Dataport for Exporting Data.

See Also

Tasks

How to: Create a Dataport for Exporting Data
How to: Change the Request Form for a Dataport
How to: Save a Dataport
How to: Run a Dataport from Object Designer
How to: Create a Dataport for Importing Data
Walkthrough: Creating a Dynamic Dataport

Concepts

Designing Dataports
Dataport Fundamentals


How to: Save a Dataport

How to: Save a Dataport

If you open a dataport object in Dataport Designer, the dataport closes when you close the Dataport Designer window.

Note Note

If you enter ID and Name as dataport properties, these values will be used, and you will not be prompted for ID and Name when you close the dataport.

You can save a dataport without closing it, and you can use the steps for saving a dataport to make a copy of an existing dataport.

To save a dataport

  1. Click File, and then click Save.

  2. In the Save As dialog box, in the ID field, enter a number that will serve as a unique identification for the dataport.

    There are restrictions about which numbers you can use. Contact your Microsoft Certified Partner for information.

  3. In the Name field, type a descriptive name for the dataport.

  4. Optionally, if you want to save the dataport without compiling it, in the Compiled field, remove the check mark.

  5. Click OK.

See Also

Tasks

How to: Create a Dataport for Exporting Data
How to: Create a Dataport for Importing Data
How to: Compile a Dataport

Concepts

Dataport Fundamentals
Designing Dataports


How to: Compile a Dataport

How to: Compile a Dataport

Dataports, like the other objects in C/SIDE, must be compiled before they can be run. You can compile a dataport when you save it, or you can test-compile it to find possible errors.

To compile a dataport to test it

  1. Open the dataport in Dataport Designer.

  2. Click Tools, and then click Compile.

This compiles the dataport without saving changes. If the dataport contains errors, it fails to compile, and you are prompted to make the appropriate changes.

See Also

Concepts

Dataport Fundamentals
Designing Dataports


How to: Run a Dataport from Object Designer

How to: Run a Dataport from Object Designer

In your completed application, your dataports are generally incorporated into menus, or they can be called, for example, from a command button on a form. However, when you are designing dataports, you often want to run them before they have been integrated into the application.

When you are designing a dataport, you can test-run it from Object Designer or Dataport Designer.

Note Note

If the dataport is for importing data, no records are saved in the database table during the test-run.

To run a dataport from Object Designer

  • In Object Designer, select the dataport that you want to run, and then click Run.

    This runs the version of the dataport that is currently saved in the database.

To run a dataport from Dataport Designer

  • Open the dataport in Dataport Designer, click File, and then click Run.

    This runs the dataport in its current stage of development. It is not saved, which means that you can use this function to verify that the changes you are making work as intended before you save them.

See Also

Tasks

How to: Create a Dataport for Exporting Data
How to: Create a Dataport for Importing Data

Concepts

Designing Dataports


Properties for a Dataport

When you design a dataport in Microsoft Dynamics NAV, you set properties on the dataport that describe the dataport and specify the format of the external file. The Import Property and FileName Property can be set and reset dynamically. For example, you can create a dataport that allows the user to decide whether to import or export, or to select the name of the external file to read from or write to. Alternatively, you can generate a file name automatically after the dataport is run.

Expand image Properties for a Dataport

The following table lists properties that you can set for a dataport.

Property Description

ID Property

The ID of the dataport—must be unique among dataports.

Name Property

The name of the dataport.

Caption Property

The caption shown on the request form window. For example, the default value in English (United States) is the same as the name of the dataport.

CaptionML Property

The list of translations of the object’s caption.

Import Property

Defines if the dataport imports or exports data. Alternatively, you can set this dynamically in the OnPreDataPort Trigger. It cannot be changed after the OnPreDataPort Trigger has been run.

FileName Property

The name of the external file to write data to or read data from. This property can be set dynamically. If you reset the file name after a file has been opened, this file is closed and a new file is opened.

FileFormat Property

Variable

—or—

Fixed

Defines the format of the external file.

FieldStartDelimiter Property

When FileFormat is Variable, this property is used to define the string that marks the beginning of a field on input or output.

FieldEndDelimiter Property

When FileFormat is Variable, this property is used to define the string that marks the end of a field on input or output.

FieldSeparator Property

When FileFormat is Variable, this property is used to define the string that separates fields on input or output.

RecordSeparator Property

The string that separates records on input or output.

DataItemSeparator Property

The string that separates data items on input or output.

UseReqForm Property

Defines if the request form should be run before the dataport is run.

Caution note Caution

If you set UseReqForm to No, the user will not be prompted to specify the name and location of the external file. If you do not provide another way to specify the external file, the dataport will cause a run-time error because no filename has been set. If the dataport runs without a user interface, you must ensure that the external file is specified elsewhere.

ShowStatus Property (Dataports)

Defines if a status window will be shown while the dataport is running. This window also has a Cancel button that you can use to interrupt the dataport run, otherwise this is only possible if you create a dialog yourself.

TransactionType Property

Browse, Snapshot, UpdateNoLocks, or Update.

The transaction type defines the behavior of a transaction in Microsoft Dynamics NAV and takes effect from the beginning of a transaction.

Permissions Property

The permissions of the dataport to access database objects. The dataport can have wider permissions than the individual user. This means that the user might be able to use dataports that retrieve information from tables that the user cannot usually access.

Expand image Remarks

The FieldStartDelimiter Property and the FieldEndDelimiter Property are used to place the contents of a field in quotation marks if the data in the field contains the character that is defined as a separator (FieldSeparator Property, RecordSeparator Property, or DataItemSeparator Property). These delimiters are not required. This means that if only one field of a record needs to be placed in quotation marks, only this field has to be enclosed by the FieldStartDelimiter Property and FieldEndDelimiter Property characters. The other fields can optionally have the delimiters; it makes no difference when you are importing. When you are exporting, all the fields are written to the external file with all the delimiters and separators.

Expand image See Also

Reference

Properties for a Data Item in a Dataport
Properties for a Field on a Dataport Data Item

Concepts

Designing Dataports
Triggers on Dataports Overview


Properties for a Data Item in a Dataport

Properties for a Data Item in a Dataport

When you design a dataport in Microsoft Dynamics NAV, you add data items and you set properties on the data items. A data item is a table in the database. Most of these properties are the same and have the same function as the corresponding properties of a data item in a report. For more information, see Data Item Properties. In dataports, data items have three additional properties: AutoSave Property, AutoUpdate Property, and AutoReplace Property.

Expand image Properties for a Data Item

The following table lists properties that you can set for a data item in a dataport.

Property | Description
DataItemIndent Property | Defines how much the data item is indented. Can be set in the designer when creating data items.
DataItemTable Property | The table that the data item is based on. Can be set in the designer when creating data items.
DataItemVarName Property | The name of the data item as a variable. The default value is the value of DataItemTable Property.
DataItemTableView Property | The key, sort order, and filters to apply. If you set this property, users cannot change values for the data item during run time, and the tab for the data item is removed from the request form.
ReqFilterHeading Property | The name of this tab on the request form. The default value is the name of DataItemTable Property.
ReqFilterHeadingML Property | The translations of ReqFilterHeading Property.
ReqFilterFields Property | The names of the fields that initially will be included in the ReqFilter form.
CalcFields Property | The names of the fields that will be calculated after a record has been retrieved.
DataItemLinkReference Property | The DataItemVarName Property of a less-indented data item that this data item will be linked to.
DataItemLink Property | The link between the current data item and the data item specified by DataItemLinkReference Property.
AutoSave Property | Defines if the imported records are automatically inserted into a C/SIDE table.
AutoUpdate Property | Defines if the imported records are initialized with values from an existing record with the same primary key.
AutoReplace Property | Defines if imported records will automatically replace existing records with the same primary key.

Expand image Remarks

The three Auto properties determine how the records that are read from the external file are handled. These properties are also used to resolve the conflict that arises when you import a record from an external file and it has the same primary key as a record that already exists in the database table.

AutoSave Property and AutoReplace Property are used to define how records are saved in the database table.

Note Note

If the value of AutoSave Property is No, the settings of AutoReplace Property and AutoUpdate Property have no effect. In this case, you have to handle any conflicts from your C/AL code.

The following table outlines the effects of various combinations of settings of these properties.

Auto Save | Auto Update | Auto Replace | Record exists in database and in import file | Record exists only in import file
No |  |  | The record in the database is not automatically updated or replaced. | The imported record is not automatically inserted in the database.
Yes | No | No | A run-time error occurs, and the import is terminated. | The imported record is automatically inserted in the database.
Yes | No | Yes | The imported record replaces the existing record. | The imported record is automatically inserted in the database.
Yes | Yes |  | The imported record updates the existing record. | The imported record is automatically inserted in the database.

Where no value is mentioned for a property, this means that the value is irrelevant.

Note Note

If AutoSave Property is set to No, it is possible to insert and modify records by using insert or modify from C/AL.

Expand image See Also

Reference

Properties for a Dataport
Properties for a Field on a Dataport Data Item

Concepts

Designing Dataports
Triggers on Dataports Overview


Properties for a Field on a Dataport Data Item

Properties for a Field on a Dataport Data Item

When you design a dataport in Microsoft Dynamics NAV, you add data items, and you set properties on the fields in the data items. If the FileFormat Property for the dataport itself is set to Fixed, you use the StartPos Property and Width Property (Dataport field) of each field to define how a record that is read from the external file is broken into fields. When you are exporting, these properties determine how data from the database is written to the external file.

Expand image Properties for a Data Item Field

The following table lists properties that you can set for a field on a data item in a dataport.

Property Description

Enabled Property

Defines if the field is enabled or disabled. A field that is disabled is imported from the external file, but will not be inserted into the record.

SourceExpr Property

The source expression of the field. When you are importing, this could be the name of the database table field where the value that is read from the external file should be stored, but it can be any valid C/AL variable. When you are exporting, this could be the value that is exported to the external file, such as the name of a database table field, but it can be any valid C/AL expression.

Caption Property

The caption in the currently selected language.

The value is taken from the CaptionML Property if this property is set. For example, the default value in English (United States) is the same as the name of the field.

CaptionML Property

The list of all the translations of the field’s caption

StartPos Property

If the FileFormat Property for the dataport itself is set to Fixed, this field defines the starting position of the data item field. Positions are numbered starting at 1.

Width Property (Dataport field)

If the FileFormat Property for the dataport itself is set to Fixed, this field defines the width of the field.

The following table describes the default values for the Width Property (Dataport field) for each field data type.

Field data type | Width assigned
Code | If actual length > 10, actual length is used, otherwise 10.
Text | If actual length > 30, actual length is used, otherwise 30
Date | 11
Time | 10
Option | 10
Decimal | 12
Integer | 7
Boolean | 10

CallFieldValidate Property

Defines if the OnValidate (Fields) Trigger is executed when the field is imported.

Format Property

Determines how the field is formatted during exportation. For example, you can determine the number of decimal places.

AutoCalcField Property

Defines if the field is a FlowField that must be automatically calculated.

Expand image Remarks

When fields are exported, the data they contain is converted to text before being exported. If the format is fixed and the width is smaller than the actual width of the data after conversion, the contents are truncated from the right until it has the defined width. That is, a number is not rounded or truncated as a number, but as text, from the right.

You get a warning at design-time if you have defined fields with starting positions and widths that could cause these fields to overlap. The error makes it impossible to compile (and subsequently execute) the dataport.

During import, a value that is too large for the data type or defined width of the database table field where it is to be inserted causes an error and execution stops. Because the whole dataport is within a transaction, no traces will be left of the failed run in the database.

Expand image See Also

Reference

Properties for a Dataport
Properties for a Data Item in a Dataport

Concepts

Designing Dataports
Triggers on Dataports Overview


Triggers on Dataports Overview

Triggers on Dataports Overview

When a dataport runs in Microsoft Dynamics NAV, certain triggers execute to update the database.

Triggers on Dataports

The following table lists triggers that execute when a dataport runs.

Trigger | Time of execution
OnInitDataPort Trigger | When the dataport is loaded, and before the request form is run and table views and filters are set.
OnPreDataPort Trigger | Before the dataport is run, but after the request form has been run. Table views and filters are set when this trigger is run.
OnPostDataPort Trigger | After all the data items have been processed.
OnPreDataItem Trigger | Before the data item is processed, but after the associated variable has been initialized and the table views and filters set.
OnBeforeExportRecord Trigger | When a record has been retrieved and is ready for export.
OnAfterExportRecord Trigger | After a record has been exported to the external file. You can use this trigger, for example, to do some processing on the external file before the next record is exported, such as moving the file pointer.
OnBeforeImportRecord Trigger | Before a record is imported from the external file. You can use this trigger, for example, to do some processing on the external file before importing the next record, such as moving the file pointer.
OnAfterImportRecord Trigger | After a record has been imported from the external file, but before it is inserted in the table. You can use this trigger, for example, to process the record before inserting it or to examine it in order to decide whether to insert it.
OnPostDataItem Trigger | When the data item has been iterated for the last time.
OnAfterFormatField Trigger | After the value of a field has been formatted, but before the text is written to the external file. This trigger gives you access to the formatted value in its text format.
OnBeforeEvaluateField Trigger | After a field has been read from the external file, but before the value has been evaluated and validated. This trigger gives you access to the imported field in text format.

See Also

Concepts

Designing Dataports


Walkthrough: Creating a Dynamic Dataport

Walkthrough: Creating a Dynamic Dataport

In this walkthrough you will learn how to create a dataport that can be used to export data as well as import data. The dataport can update prices in the Item table in an external program such as Microsoft Office Excel.

Expand image About This Walkthrough

This walkthrough provides an overview of how to create a dataport with Microsoft Dynamics NAV. The walkthrough illustrates the following tasks:

  • Creating a dataport that can export data from the Item table to an external file.

  • Modifying the dataport to import data into the Item table from an external file.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV installed with a developer license.

  • The CRONUS International Ltd. demo data company installed.

  • An external editor, such as Microsoft Excel, which can open a .csv file.

To create a dataport

  1. Click Tools, and then click Object Designer.

  2. In Object Designer, click Dataport, and then click New.

  3. In the Properties window for the new dataport, set the following properties.

    Property Value

    FileFormat Property

    Variable

    FieldStartDelimiter Property

    "

    FieldEndDelimiter Property

    "

    FieldSeparator Property

    ;

    In this walkthrough, the format of the external file is variable and uses a semicolon as the field separator. This is because the external editor is Microsoft Excel, and for this use, a .csv file is appropriate.

You have created a dataport and must now specify which tables and fields will be used in the dataport.

Expand image Enabling the Dataport to Export Data

In the previous section, you created a dataport. Now, you will add a data item for the Item table.

To add a data item for the Item table

  1. In Dataport Designer, in the first DataItem field, click the AssistButton, and then select the Item table.

  2. In the Properties window of the Item data item, in the DataItemTableView property, click the AssistButton.

  3. In the Table View window, in the Key field, click the AssistButton, and in the Key List window, select the No. field.

    In this walkthrough, you will not use Table Filter field to set a filter even though you want to export a subset of the records in the Item table. Instead, you will set the filter in C/AL code in the next procedure.

  4. Click View, and then click C/AL Globals.

  5. In the C/AL Globals window, create a global variable called Tariff Number of data type Record, with the Tariff Number table as the subtype.

Next, you add fields to the data item.

To add fields to the Item data item

  1. In Dataport Designer, select the Item data item, click View, and then click Dataport Fields.

  2. In Field Designer, in the first row, in the SourceExpr field, click the AssistButton, and then in the Field List window, select the No. field.

  3. Repeat step 2 to add the Description and Unit Price fields.

  4. In the fourth row, in the SourceExpr field, type "Tariff Number".Description.

    This adds the Description field to the data item by using the Tariff Number global variable.

    In Field Designer, the StartPos Property and Width Property (Dataport field) are automatically set for some of the fields. You can calculate the appropriate values by looking up the length of each field. The first field always has a start position of 1. The Unit Price field is of data type Decimal and its length must therefore be 12.

    For more information, see Properties for a Field on a Dataport Data Item.

    The following table lists the values for each of the fields.

    SourceExpr StartPos Width

    "No."

    1

    20

    "Description"

    22

    30

    "Unit Price"

    53

    12

    "Tariff Number".Description

    66

    50

  5. To set the filter that will select the records between numbers 1000 and 2000 where the Gen. Prod. Posting Group is RETAIL, open the C/AL editor, and enter the following code in the OnPreDataItem Trigger of the Item data item.

    CopyCode image Copy Code
    IF NOT CurrDataport.IMPORT THEN
  Item.SETRANGE("Gen. Prod. Posting Group",’RETAIL');
  Item.SETRANGE("No.",’1000',’2000’);

    The filter is set only if the dataport is used to export. The reason for using this construction instead of setting a table filter in the DataItemTableView Property is that if you are placing the filter on a field that is not being exported with the other data. If you had used the TableFilter Data Type, the filter would always be set, including when the dataport is used to import data. However, because the Gen. Prod. Posting Group field is not in the file that you import, no records will be imported. If the field that you use for filtering is exported and imported, you could use the TableFilter field in the Table View window to set the filter.

  6. To retrieve the text from the Tariff Number table and to export it, enter the following code in the OnBeforeExportRecord Trigger of the data item.

    CopyCode image Copy Code
    IF "Tariff No." <> '' THEN
BEGIN
  "Tariff Number"."No." := "Tariff No.";
  "Tariff Number".FIND;
END
ELSE
  "Tariff Number".Description := 'NO TARIFF NUMBER';

  7. Save and compile the dataport.

Expand image Enabling the Dataport to Import Data

In the previous section, you created a dataport and enabled it for exporting data. Now, you will enable the dataport to import prices that have been modified in an external file.

To enable the dataport to import modified prices

  1. In Dataport Designer, select the Item data item, and in the Properties window for the data item, set the following properties.

    Property Value

    AutoSave

    Yes

    AutoUpdate

    Yes

    These settings update the existing records with the data that is different in the imported records, in this case, the unit price. For more information, see Properties for a Data Item in a Dataport.

  2. Save changes to the dataport.

Expand image Testing the Dynamic Dataport

You have created a dataport that can export data from the Item table, and which can import modified data into the Item table. Now, you can test that it works as expected.

To test the dataport

  1. Click File, and then click Run to run the dataport.

  2. In the request form, set the following properties.

    Property Value

    FileName

    Prices.csv

    Direction

    Export

  3. Click OK.

    The dataport runs, and the records that match the criteria you have set up are written to a file called Prices.csv.

  4. Open the Prices.csv file in Microsoft Excel.

    The following table illustrates the result of exporting the data.

    1000

    Bicycle

    4,000

    1001

    Touring Bicycle

    4,000

    1100

    Front Wheel

    1,000

    1110

    Rim

    0

    1150

    Front Hub

    500

    1200

    Back Wheel

    1,200

    1250

    Back Hub

    1,100

    1300

    Chain Assy

    800

    1310

    Chain

    0

    1700

    Brake

    600

    1710

    Hand rear wheel Brake

    0

  5. In Microsoft Excel, change some of the unit prices.

    The following table illustrates how you can change prices.

    1000

    Bicycle

    4,500

    1001

    Touring Bicycle

    4,000

    1100

    Front Wheel

    1,000

    1110

    Rim

    10

    1150

    Front Hub

    500

    1200

    Back Wheel

    1,200

    1250

    Back Hub

    1,100

    1300

    Chain Assy

    800

    1310

    Chain

    20

    1700

    Brake

    600

    1710

    Hand rear wheel Brake

    20

    In the example, the prices for items 1000, 1110, 1310, and 1710 have been changed.

  6. Save the changed file as NewPrices.csv.

  7. To import the new data, run the dataport and fill out the request form as shown in the following table.

    Property Value

    FileName

    NewPrices.csv

    Direction

    Import

    Note Important

    The records are not imported if you run the dataport from inside Dataport Designer. You must run it from, for example, Object Designer.

The item unit prices are updated according to the changes that you made in Microsoft Excel.

Expand image Next Steps

For this example, the price of each unit is used to calculate the Profit % field in the Item table when the field is validated. You have not used the CallFieldValidate Property to enforce that evaluation, but have left it at the default setting of No. Getting the validation to work as intended is not so easy, because the code that is triggered uses values from other fields that are not part of this dataport. At the time of the validation, these fields do not contain any values because they are updated later.

One way to solve this problem would be to export all the fields but this would make it harder to manage in Microsoft Excel. This problem shows that you must give careful consideration to all the interdependent data when you update a table from a dataport. The solution to the problem will, however, be different for each table and for each set of fields that are imported.

Expand image See Also

Tasks

How to: Save a Dataport
How to: Run a Dataport from Object Designer
How to: Create a Dataport for Exporting Data
How to: Create a Dataport for Importing Data

Concepts

Designing Dataports
Dataport Fundamentals


Creating XMLports

Creating XMLports

XMLports are conceptually related to dataports because they are object types that can import and export data. The difference is that the data in XMLports is encapsulated in XML format. This makes it possible to exchange information between different computing systems in a streamlined way.

Introducing XMLports

To | See
Get introduced to XMLports. | XMLport Fundamentals
Read about the XMLport Designer. | XMLport Designer Window
Read about triggers available for XMLports and XMLport elements. | XMLport Triggers

Examples of XMLports

To | See
See an example of how you can use an XMLport to import data from an XML document into Microsoft Dynamics NAV. | XMLport Sales Order Example
See an example of when an XML document contains multiple data values that are represented only by one data structure in the Microsoft Dynamics NAV database. | XMLport Multiple Data Values Example
See an example of an XML document where some values are being repeated for data-linking purposes in Microsoft Dynamics NAV. | XMLport Repeating Data Example
Read about what you can do if an XML document does not contain all necessary information. | XMLport Document With Insufficient Information
Read about special XMLports for systems with business notifications. | XMLport and Business Notifications
Learn about XML documents and flat data structures. | XMLport Document Containing Data in Different Scopes
Follow step-by-step procedures that show how to upload a file from a client to the server, read the file, and use an XMLport to load values into the database. | Walkthrough: Uploading a File from a Client to Microsoft Dynamics NAV Server

See Also

Concepts

Designing XMLports


XMLport Fundamentals

XMLport Fundamentals

XMLports enable you to import data received in XML format to the Microsoft Dynamics NAV database and export data in XML format from the Microsoft Dynamics NAV database. You only need a basic knowledge of XML to design and work with XMLports. You design XMLports in XMLport Designer, which you open from Object Designer.

Saving, Compiling, and Running an XMLport

When you have designed an XMLport, you must save and compile it before you can use it. Usually, you do this when you have finished designing the XMLport. However, you may want to save an XMLport that is not yet finished and therefore cannot be compiled. You can also test-compile an XMLport without closing or saving it.

Compiling an XMLport

XMLports, like other objects in C/SIDE, must be compiled before they can be run. As described previously, you can choose to compile an XMLport when you save it.

While you are designing an XMLport, you may want to test-compile it to find possible errors. To test-compile an XMLport during design, choose the Compile option in the Tools menu.

Running an XMLport

XMLports are called from codeunits. While you are designing an XMLport, you may want to run it before it has been integrated into an application to check that it functions as you intended. To do so, you can create a test-run codeunit that calls the XMLport and either streams data to or from a file depending on whether you are importing or exporting data. The following is an example of a test-run codeunit that calls an XMLport to import data from an XML file. The code is implemented in the OnRun method.

CopyCode image Copy Code
TestFile.OPEN('C:\XML-Test\XML Import\Import.xml');
TestFile.CREATEINSTREAM(TestStream);
XMLPORT.IMPORT(74300, TestStream);
TestFile.CLOSE;

The four functions in the OnRun section perform the following:

  • Open the Import.xml file.

  • Create an InStream object so that the XML data can be streamed from the file.

  • Load a specific XMLport object and give it the source from which it can read and parse the incoming XML data stream.

  • Close the Import.xml file.

See Also

Concepts

Designing XMLports


Designing XMLports

Designing XMLports

An XML document contains XML nodes, which identify the type of the content that they contain. You create XMLports with Object Designer in Microsoft Dynamics NAV.

Designing an XMLport

To create an XMLport that imports the data in an XML document, you specify all the XML node names and indicate the type for each node to indicate whether it represents an element or an attribute. You then map these node names to corresponding data structures, such as tables, records, or fields, in the Microsoft Dynamics NAV database.

At run time, when an XMLport object is called to handle an incoming XML document, it reads the incoming data stream and performs the processing and database actions. When you want to create an XMLport to export data from the Microsoft Dynamics NAV database in XML format, you use the XMLport Designer to build the node structure of the XML document and map the data. At run time, the XMLport object reads the required data from the database, adds the necessary XML nodes to form the XML document, and writes the document to a data stream.

XMLports do not handle XML documents that:

  • Modify existing data in the database.

  • Find and delete data in the database.

  • Query the database for data, such as item catalog information.

If you need to work with an incoming document of one of these types, then you can use C/AL code to manipulate the database to achieve the desired result.

Note Note

Do not use a semicolon within a quoted argument as a field value when importing a file through an XMLport. Even within a quoted argument, the semicolon is interpreted as a record separator.

See Also

Concepts

XMLport Designer Window
XMLport Fundamentals


XMLport Designer Window

XMLport Designer contains four column fields: Node Name, Node Type, Source Type, and Data Source.

XMLport Designer Window

The type of information that you enter in XMLport Designer column fields is shown in the following table.

Field name Description

Node Name

In the Node Name field, you enter the XML node name of the XML element or attribute. You must enter node names in the order in which they appear in the XML document. Parent elements must precede their child elements. You indent the node names of child elements under their parent elements using one indentation per level. You list attributes under the elements that they define and you indent them to the child level.

Node Type

You use this field to specify whether the name in the Node Name field represents data of the type element or attribute. The drop-down list in a Node Type field contains two options: Element and Attribute. The default setting is Element.

Source Type

You use this field to specify the data structure that the node name corresponds to in the Microsoft Dynamics NAV database. The Source Type field contains a drop-down list containing three options: Text, Table, and Field. The default setting is Text.

  • Text

    Select this is the option when the XML data cannot be mapped directly to the database or when the database does not need the information. The value of the Text field will be put into a text variable with the name you have specified in the VariableName property (otherwise the node name will be used by default). The text variable acts like a normal global C/AL text variable. You can also turn the text source type into a big text variable by setting the TextType property to BigText.

  • Table

    Select this option to indicate that the node name is equivalent to a table or that a table record must be initialized. As with the Text option, you can specify a variable name for the table, which also acts like a global record variable. By default, the variable name is the name of the table.

  • Field

    Select this option to indicate that the node name is equivalent to a field in the database. However, for this selection to be valid, you must first have declared a table as the parent of the field. Failure to do so will cause an error to occur when you try to compile the XMLport object.

Data Source

A Data Source field has the following interactions with the Source Type field:

  • If Source Type is set to Table and you have defined a variable name for the table to be used, the format of the value shown in the DataSource field will be tablevariablename(tablename). If you have not defined a variable name, the format of the value will be shown as <tablename>(tablename).

  • If Source Type is set to Field select a field from one of the tables you have specified in the XMLport. The format of the value is shown as tablevariablename::fieldname.

XMLport Properties, Functions, and Triggers

There are a set of properties, functions, and triggers that you can use to manipulate an XMLport. There are properties, functions, and triggers for the object level, and for the element level, which consists of Field, Table, and Text. The properties that are available at the element level depend on the selections you make in the Node Type and Source Type fields in XMLport Designer. For more information, see C/SIDE Reference Guide.

See Also

Concepts

Designing XMLports
XMLport Fundamentals


XMLport Sales Order Example

XMLport Sales Order Example

This topic contains an example showing how you can use an XMLport to import data from an XML document into the Microsoft Dynamics NAV database.

Example

In this example, you design an XMLport to import data from an XML sales order document, XML Sales Order.xml, to the Microsoft Dynamics NAV database. The following code example shows the sales order.

CopyCode image Copy Code
<?xml version="1.0" ?>
<HeaderLines>
  <SalesOrder>
    <Header Date="17-02-04" Type="Quote">
      <SellTo CountryRegion="GB">
       <Name>The Cannon Group PLC</Name>
       <Address>192 Market Square</Address>
       <City>Birmingham</City>
       <Zip>B27 4KT</Zip>
     </SellTo>
     <BillTo CountryRegion="GB">
       <Name>The Cannon Group PLC</Name>
       <Address>192 Market Square</Address>
       <City>Birmingham</City>
       <Zip>B27 4KT</Zip>
     </BillTo>
     <Lines>
       <Item PartNum="LS-150">
         <ProductName>Loudspeaker, Cherry, 150W</ProductName>
         <Quantity>8</Quantity>
         <UnitPrice>129,00</UnitPrice>
         <ShipmentDate />
         <Comment>Confirm the voltage is 75W</Comment>
       </Item>
          <Item PartNum="LS-MAN-10">
          <ProductName>Manual for Loudspeakers</ProductName>
          <Quantity>20</Quantity>
          <UnitPrice />
          <ShipmentDate />
          <Comment />
       </Item>
          <Item PartNum="LS-2">
            <ProductName>Cables for Loudspeakers</ProductName>
            <Quantity>10</Quantity>
            <UnitPrice>21,00</UnitPrice>
            <ShipmentDate />
            <Comment />
            </Item>
     </Lines>
     <Contact>Mr. Andy Toal</Contact>
     <Terms>14 days</Terms>
    </Header>
  </SalesOrder>
</HeaderLines>

After analyzing the XML document, you can see that the data belongs in two database tables: XML Header - Import and XML Items - Import. You need to design an XMLport that can insert the data into these tables.

The design of the XMLport shows that the data in the XML document has been mapped to database tables which have a header-line relation. The XMLport must insert the header information before inserting the line information. You need to set the LinkedTableForcedInsert property to Yes for the <Item> node to ensure that this happens. The LinkTable and LinkFields properties for this node also need to be set to indicate the relationship between the XML Header - Import and XML Items - Import tables. It is important to specify this binding information to ensure that the XMLport enters the data into the correct tables. Note that you have given the XML Items - Import table the variable name L and that the XML Header - Import table has the variable name H. The following table shows the properties for the <Item> node.

Property | Value
Indentation | 4
NodeName | Item
NodeType | Element
SourceType | Table
SourceTable | XML Items - Import
VariableName | L
SourceTableView | <Undefined>
CalcFields | <Undefined>
LinkTable | H
LinkTableForceInsert | <Yes>
LinkFields | Doc No=FIELD(Order No)
Temporary | <No>
Width | <0>
MinOccurs | <Once>
MaxOccurs | <Unbounded>

After all the records have been inserted into the XML Items - Import table, the Contact Person and Payment Terms fields in the XML Header - Import table have to be updated. You can do this by adding the following C/AL code line on the Contact - Import::OnAfterAssignField() trigger and on the Terms - Import::OnAfterAssignField() trigger:

CopyCode image Copy Code
H.MODIFY;

See Also

Concepts

Designing XMLports
XMLport Fundamentals
XMLport Multiple Data Values Example
XMLport Repeating Data Example
XMLport Document With Insufficient Information
XMLport and Business Notifications
XMLport Document Containing Data in Different Scopes


XMLport Multiple Data Values Example

XMLport Multiple Data Values Example

The following example shows how to handle a situation in which an XML document contains multiple data values that are represented by only one data structure in the Microsoft Dynamics NAV database. For an XMLport Sales Order example, see XMLport Sales Order Example.

Example

In this example, the XML sales order document from which you want to import data into the table contains two nodes <ShipDate> and <ShipTime>, as shown in the following.

CopyCode image Copy Code
<?xml version="1.0" ?>
  <SalesOrder>
    <OrderHeader OrderDate="17-09-04">
      <SellTo CountryRegion="GB">
        <Name>The Cannon Group PLC</Name>
        <Address>192 Market Square</Address>
        <City>Birmingham</City>
        <Zip>B27 4KT</Zip>
      </SellTo>
      <BillTo CountryRegion="GB">
        <Name>The Cannon Group PLC</Name>
        <Address>192 Market Square</Address>
        <City>Birmingham</City>
        <Zip>B27 4KT</Zip>
        <PaymentTerms>14days</PaymentTerms>
      </BillTo>
    </OrderHeader>
    <Items>
      <Item PartNum="LS-75">
        <ProductName>Loudspeaker, Cherry, 75W</ProductName>
        <Quantity>10</Quantity>
        <UnitPrice>79</UnitPrice>
        <ShipDate>12-10-04</ShipDate>
        <ShipTime>09:50</ShipTime>
        <Comment>Confirm the voltage is 75W</Comment>
      </Item>
      <Item PartNum="1908-8">
        <ProductName>LONDON Swivel Chair, blue</ProductName>
        <Quantity>12</Quantity>
        <UnitPrice>190,926</UnitPrice>
        <ShipDate>12-10-04</ShipDate>
        <ShipTime>09:50</ShipTime>
      </Item>
    </Items>
  </SalesOrder>

One solution to the problem in this example is to cache the values in the <ShipDate> and <ShipTime> nodes, format the two values into a DateTime value, and assign the formatted value to the Shipping Time field in the Sales Lines table. In XMLport Designer, you would define the <ShipDate> and <ShipTime> nodes as being of the Text source type.

Node name | Node type | Source type | Data source
ShipDate | Element | Text | <ShipDate>
ShipTime | Element | Text | <ShipTime>

In the OnAfterAssignVariable trigger for the <ShipTime> node, you would write code that formats the two text variables into one DateTime variable and assigns the value held by that variable to the Shipping Time field in the Sales Lines table.

See Also

Concepts

XMLport Sales Order Example


XMLport Repeating Data Example

XMLport Repeating Data Example

In a business document, you typically do not state the same information more than once. In a relational database, however, certain information must be repeated in various tables for data linking purposes.

Example

In the following XML sales order document, the <Items> node has the attribute Type="Order".

CopyCode image Copy Code
<?xml version="1.0" ?>
  <SalesOrder>
    <OrderHeader OrderDate="17-01-04">
      <SellTo CountryRegion="GB">
        <Name>The Cannon Group PLC</Name>
        <Address>192 Market Square</Address>
        <City>Birmingham</City>
        <Zip>B27 4KT</Zip>
      </SellTo>
      <BillTo CountryRegion="GB">
        <Name>The Cannon Group PLC</Name>
        <Address>192 Market Square</Address>
        <City>Birmingham</City>
        <Zip>B27 4KT</Zip>
        <PaymentTerms>14days</PaymentTerms>
      </BillTo>
    </OrderHeader>
    <Items Type="Order">
      <Item PartNum="LS-75">
        <ProductName>Loudspeaker, Cherry, 75W</ProductName>
          <Quantity>10</Quantity>
          <UnitPrice>79</UnitPrice>
          <ShipDate>12-10-04</ShipDate>
          <ShipTime>09:50</ShipTime>
          <Comment>Confirm that the amount of power is 75W</Comment>
      </Item>
      <Item PartNum="1908-8">
        <ProductName>LONDON Swivel Chair, blue</ProductName>
          <Quantity>12</Quantity>
          <UnitPrice>190,926</UnitPrice>
          <ShipDate>12-10-04</ShipDate>
          <ShipTime>09:50</ShipTime>
      </Item>
    </Items>
  </SalesOrder>

For this example, the Type="Order" information must be written to the Document Type field of the relevant table, the XML Sales Lines table. To cache the "Order" value, you would declare the Type attribute as a Text source type.

Node name | Node type | Source type | Data source
Type | Attribute | Text | Type

To assign the Type value to each record in the XML Items - Import table, you could write the following code in the Import::OnAfterInitRecord trigger for the <Item> node: L.Document Type := Type;

See Also

Concepts

XMLport Multiple Data Values Example
XMLport Sales Order Example


XMLport Document With Insufficient Information

XMLport Document With Insufficient Information

Sometimes an incoming XML document may not contain sufficient information to allow you to insert certain data as a record.

Example

To solve the problem of insufficient information, you can preassign the values of the fields for which you do not have data. You can do this in the Import::OnAfterInitRecord and Import::OnBeforeInsertRecord triggers. If, for example, you receive an XML sales order document that does not contain Line No. information, you can assign a value for it by adding the following lines.

CopyCode image Copy Code
If not SL.Line No. then
SL.Line :=1001;

See Also

Concepts

XMLport Sales Order Example
XMLport Multiple Data Values Example
XMLport Repeating Data Example


XMLport and Business Notifications

XMLport and Business Notifications

If you are running Microsoft Business Notifications with Microsoft Dynamics NAV, you can associate XMLport events with an XMLport. Users who run Business Notifications can then subscribe to these events. For example, you could define the event Sales Order Created for a Sales Order XMLport. You will usually design special XMLports for the Business Notifications system.

Events

XMLport events are called from codeunits to raise an event to Business Notifications. The XMLport then sends an XML document to the Business Notifications system. Based on the content of the XML document and the event raised, the Business Notifications system will send event information to subscribers. For example, in the case of the Sales Order Created event, it will check to see who has subscribed to this event and send them e-mail notification that a sales order has been created.

The events that you define can be more detailed than simply Sales Order Created. For example, you can define an event that is raised when the total amount of a sales order exceeds a certain amount.

Example

You want to raise an event that provides notification when a customer is blocked, that is, when Blocked changes from false to true. You therefore design an XMLport that contains the necessary data, for example, the ID and Name of the customer, and the date when the change occurred. You define an event called Blocked in XMLport Event Designer and you declare the XMLport as a local variable called CustXMLDoc. Finally, you add the following code to the OnModify trigger in the Customer table:

CopyCode image Copy Code
IF Blocked = TRUE THEN
  IF Blocked <> xRec.Blocked THEN
    CustXMLDoc.Blocked();

See Also

Concepts

XMLport Sales Order Example
XMLport Multiple Data Values Example
XMLport Repeating Data Example
XMLport Document With Insufficient Information
XMLport Document Containing Data in Different Scopes


XMLport Document Containing Data in Different Scopes

XMLport Document Containing Data in Different Scopes

An XML document can be described as having a tree structure with many levels. A database table, however, can only store data in a flat structure—at the field level. For example, an incoming XML document can contain data in different scopes, where the data belongs in the same scope in the database.

Example

The <BillTo> node of an XML sales order document could contain a <PaymentTerms> child element. The value of the <PaymentTerms> node might sometimes need to be assigned to all sales items, and sometimes to only one of them. If you declare the <PaymentTerms> node as the Element node type and the Text source type, the XMLport can store the value and therefore when it starts to process the sales item information, you can specify which records the value is to be assigned to.

To avoid writing data directly to a table, you can apply a stylesheet to the XML document to ensure that the XML node names are transferred in the correct order.

Alternatively, you could design an XMLport that writes the data to a temporary table. You could then write code that inserts the data into the relevant table using the correct order. The following code example shows an XML sales order document that contains a <DocumentNo> node.

CopyCode image Copy Code
<Items>
  <Item PartNum="LS-75">
    <ProductName>Loudspeaker, Cherry, 75W</ProductName>
      <Quantity>10</Quantity>
<UnitPrice>79</UnitPrice>
<Comment>Confirm the voltage is 75W</Comment>
   </Item>
   <Item PartNum="1908-8">
     <ProductName>LONDON Swivel Chair, blue</ProductName>
       <Quantity>12</Quantity>
 <UnitPrice>190,926</UnitPrice>
 <ShipDate>12-05-04</ShipDate>
 <DocumentNo>9999</DocumentNo>
   </Item>
</Items>

The value of this node, the number of the document, needs to be written to the Sales Header table in the database. Before this can happen, the value needs to be checked to ensure that it is valid. However, the XMLport design will not work because the position of the <DocumentNo> node violates the validation order of the Sales Lines table.

To solve the problem, you could assign the XML node names that were mapped to the Sales Lines table to a temporary table. You could then write code that assigns the value of the <DocumentNo> node to the correct table, and in the correct validation order, after the value has been assigned to a temporary table record. This means that the <DocumentNo> value must be copied from the temporary record to the real record before any of the other fields are copied to the Sales Lines table.

By using temporary tables, you will be able to solve most of the cases where you can see that an incoming XML document contains nodes in a sequence that would violate the database validation order.

See Also

Concepts

XMLport Sales Order Example
XMLport Multiple Data Values Example
XMLport Repeating Data Example
XMLport Document With Insufficient Information


Designing MenuSuites

Designing MenuSuites

When you create new forms or reports, you can insert these into menus as menu items. A menu suite is a set of menus. The MenuSuite object contains the main menu content, which is displayed in the navigation pane and you can design in Navigation Pane Designer.

Introducing MenuSuite Objects

To | See
Learn the purpose and function of MenuSuite objects in Microsoft Dynamics NAV applications. | MenuSuite Object Fundamentals

Creating and Designing MenuSuite Objects

To | See
Learn about design levels for creating MenuSuite objects. | Designing MenuSuite Objects
Create a new MenuSuite object. | How to: Create and Modify a MenuSuite Object
Modify an existing MenuSuite object. | How to: Create and Modify a MenuSuite Object
Create a menu item in Navigation Pane Designer. | How to: Customize a MenuSuite Object
Export a MenuSuite object file. | How to: Export a MenuSuite Object
Save and compile a MenuSuite object. | How to: Compile a MenuSuite Object


MenuSuite Object Fundamentals

MenuSuite Object Fundamentals

The MenuSuite object contains the main menu content that is displayed in the navigation pane and in Navigation Pane Designer. A menu suite is a set of menus. Each menu contains content for a specific department, for example, Finance or Manufacturing. This section introduces the fundamental concepts and basic tasks needed to create and design MenuSuite objects.

The content of a MenuSuite object can be described as having the following characteristics:

  • It consists of a set of menus.

  • A menu contains a collection of menu nodes, which display in the navigation pane or in Navigation Pane Designer in a tree structure.

  • A menu node can be either a menu group or a menu item.

  • A menu node has a globally unique identifier (GUID) and various properties.

  • A menu group contains a collection of menu nodes.

  • A menu item is the lowest level in the tree. When you click a menu item, its associated form, report, batch job, dataport, or codeunit runs.

Design Permissions

When you create new forms or reports, you can insert these into menus as menu items. You can also make modifications to existing application objects. You have the same design permissions as an administrator. As a developer working as a Microsoft Certified Partner, you have permission to create a MenuSuite object at the Partner level. You also have permission to create a MenuSuite object at the Company level, which can be useful for testing before you supply a company with a MenuSuite object.

See Also

Concepts

Designing MenuSuite Objects
Designing MenuSuites


Designing MenuSuite Objects

Designing MenuSuite Objects

MenuSuite objects contain the menu content that you want to display in the application. You create a MenuSuite object in Object Designer after which you can design and customize the menu content in Navigation Pane Designer. This means that you can create new menu items, group menu items, and move them around to design the final output of a menu suite.

When you create a new MenuSuite object, you must choose a design level for this.

MenuSuite Object Levels

Microsoft Dynamics NAV provides a generic MenuSuite object at base application level. This object is changed in various ways before end users see its content. These changes are applied at different levels, which are categorized as Country/Region, Add-on, Partner, and Company. For example, the MenuSuite object is changed when the application undergoes localization changes, which takes place at the Country/Region level. If you are a developer working at a Microsoft Certified Partner, you customize a MenuSuite object at the Partner level. You can also configure a MenuSuite object at the Company level, which is the level that administrators work on.

Changes that are made to a MenuSuite object are stored as the differences between the previous MenuSuite object level and the current one. For example, when a company administrator configures a MenuSuite object at the Company level, the modifications are stored as the differences between the Company level and the Partner level, which was the previous level.

If you export a MenuSuite object in text format and then open the text file, you will see information about the changes that you have made. For more information, see How to: Export a MenuSuite Object.

With the exception of the Add-on MenuSuite object, for which a maximum of 10 instances is allowed, there can only be one MenuSuite object for each level.

See Also

Tasks

How to: Create and Modify a MenuSuite Object
How to: Customize a MenuSuite Object
How to: Export a MenuSuite Object
How to: Compile a MenuSuite Object

Concepts

Upgrading MenuSuite Objects


How to: Create and Modify a MenuSuite Object

How to: Create and Modify a MenuSuite Object

The MenuSuite object contains the main menu content that is displayed in the navigation pane and in Navigation Pane Designer. A menu suite is a set of menus. Each menu contains content for a specific departmental area, for example, Finance or Manufacturing. You create a MenuSuite object in Object Designer after which you can design and customize the menu content in Navigation Pane Designer. For more information about customizing menu content, see How to: Customize a MenuSuite Object. The following procedures describe how to create or modify a MenuSuite object from Object Designer.

To create a MenuSuite object

  1. On the Tools menu, click Object Designer to open the Object Designer window.

  2. In Object Designer, click MenuSuite, and then click the New button to create a new MenuSuite object in Navigation Pane Designer.

  3. This opens a dialog box asking you to specify which design level you want to create an object for. If you have already created a MenuSuite object for all the levels you have permission to, a message will appear informing you of this. After you have made a selection, Navigation Pane Designer opens.

    Note Note

    The MenuSuite object level that you are working on is shown in the header section of Navigation Pane Designer.

  4. In Navigation Pane Designer, right-click a menu item to select a task from the shortcut menu. For more information about creating a menu item, see How to: Customize a MenuSuite Object.

  5. Right-click the navigation pane, and click Close Navigation Pane Designer when you are done.

To modify an existing MenuSuite object

  1. On the Tools menu, click Object Designer to open the Object Designer window.

  2. In Object Designer, click MenuSuite.

  3. Select the MenuSuite that you want to modify, and then click Design.

    This opens Navigation Pane Designer with the chosen menu suite content displayed. The MenuSuite object level is shown in the header section of Navigation Pane Designer.

  4. In Navigation Pane Designer, right-click a menu item to select a task from the shortcut menu.

  5. Right-click the navigation pane, and then click Close Navigation Pane Designer when you are done.

    Note Note

    The MenuSuite also defines the Departments section of the RoleTailored client. If the RoleTailored client is currently open, you will not see your changes to until to you close and restart it. For more information about Departments, see Touring the RoleTailored Client Windows.

See Also

Tasks

How to: Compile a MenuSuite Object
How to: Customize a MenuSuite Object
How to: Export a MenuSuite Object

Concepts

Upgrading MenuSuite Objects
Designing MenuSuite Objects


How to: Compile a MenuSuite Object

How to: Compile a MenuSuite Object

You can compile MenuSuite objects like the other objects in C/SIDE. It is the object references that are compiled. You can compile a MenuSuite object when you save it, or you can test-compile it to find possible errors. If the MenuSuite object contains a reference to a non-existing form, report, batch job, dataport, or codeunit, a compilation error occurs.

To compile a MenuSuite object

  1. Open the MenuSuite object in Navigation Pane Designer.

  2. Click Tools, and then click Compile.

    Note Note

    The Run button in Object Designer is disabled when you click the MenuSuite button because a MenuSuite object cannot be run.

See Also

Tasks

How to: Create and Modify a MenuSuite Object
How to: Customize a MenuSuite Object
How to: Export a MenuSuite Object

Concepts

Upgrading MenuSuite Objects
Designing MenuSuite Objects


How to: Customize a MenuSuite Object

How to: Customize a MenuSuite Object

You customize a menu suite in Navigation Pane Designer. To access design options, right-click menu buttons, menu groups, menu items. or anywhere in the content pane area. The following procedure describes how you can customize a MenuSuite object by creating a menu item in Navigation Pane Designer. For more information about creating MenuSuite objects, see How to: Create and Modify a MenuSuite Object.

To create a menu item in Navigation Pane Designer

  1. In Navigation Pane Designer, right-click the content pane area, a menu group, or a menu item, and then click Create Item.

  2. In the Create Item window, fill in the following fields.

    Field Definition

    Object Type

    The following object types are available from the drop-down box: Table, Form, Report, Batch Job, Codeunit, Dataport.

    Object ID

    To select a specific object from a list. For example, if you select Report as the object type, then the Report List window displays.

    Caption

    By default, contains the name that has been assigned to the menu item. You can rename it here if you want.

    CaptionML

    Contains the code for the language that you use on your computer and the name of the menu item, for example, ENU=General Journals. If the menu item will be used in different languages by different users, you must give the menu item a name in each language. When you click the AssistButton, the Multilanguage Editor window opens where you can enter a menu item name for each language code.

  3. Click OK.

    Note Note

    The MenuSuite also defines the Departments section of the RoleTailored client. If the RoleTailored client is currently open, you will not see your changes until you close and restart it. For more information about departments, see Touring the RoleTailored Client Windows.

See Also

Tasks

How to: Create and Modify a MenuSuite Object
How to: Export a MenuSuite Object
How to: Compile a MenuSuite Object

Concepts

Upgrading MenuSuite Objects
Designing MenuSuite Objects


How to: Export a MenuSuite Object

How to: Export a MenuSuite Object
See Also Example

You can export a MenuSuite object in Microsoft Dynamics NAV object format (*.fob) or in text format. The text file contains information about the changes that have been made to the object since the previous level. For example, if you export a MenuSuite object in text format and then open the text file, you will see information about the changes that you have made, seen in relation to the previous level. For more information about MenuSuite Object levels, see Designing MenuSuite Objects. In the following procedure you can see how to export a MenuSuite object and an example of a text file that contains the changes that have been made to a MenuSuite object at the company level.

To export a MenuSuite object

  1. Click File, and then click Export.

  2. In the Export Objects window, select the location where you want to export the file.

  3. In File name, enter an appropriate name for the file.

  4. In Save as Type, select the format type, and then click Save.

Example

When an administrator makes configuration changes to a menu suite, these changes are saved at the company level. When this MenuSuite object is exported in text format, the text file contains information about the changes that have been made to the object since the previous level, such as the partner level. In the following example, the administrator has made the following changes to the company's menu suite:

  • On the Finance menu, deleted a menu group called Setup, which contained one menu item called Accounting Periods.

  • On the General Ledger menu, added a new menu item, G/L Account Card, to a group in the Finance menu.

  • On the General Ledger menu group, moved the G/L Account Card menu item so that it is placed between the Chart of Accounts and Bank Accounts menu items.

In this example, the text file contains the following information.
CopyCode image Copy Code
OBJECT MenuSuite 70 Company
{
  OBJECT-PROPERTIES
  {
    Date=19-04-04;
    Time=16:04:10;
    Modified=Yes;
    Version List=;
  }
  PROPERTIES
  {}
  MENUNODES
  {
    { MenuItem ;[{FA8395A4-7A0B-4524-B0FD-20436D9711A4}] ;Name=G/L Account Card;
      CaptionML=ENU=G/L Account Card;
      MemberOfMenu=[{F8D2429D-034B-4C58-9B5E-81BE962DB1BC}];
      RunObjectType=Form;
      RunObjectID=17;
      ParentNodeID=[{B12180CF-0EFB-43AD-9118-7765E953AAFD}];
      Visible=Yes;
      NextNodeID=[{7A5B6DDE-B44B-41A0-95DA-69B7109F0E32}]
    }
    { ;[{1BB06483-AFFD-4750-BF62-3ABA035E11B7}];
      Deleted=Yes}
      { ;[{DF601C8A-07F7-4841-8929-9F2065BCB302}];
      Deleted=Yes}
      { ;[{8AC7917D-2C91-457D-80D6-A24B42F71AE7}];
      NextNodeID=[{FA8395A4-7A0B-4524-B0FD-20436D9711A4}]
    }
  }
}

See Also

Tasks

How to: Create and Modify a MenuSuite Object
How to: Customize a MenuSuite Object
How to: Compile a MenuSuite Object

Concepts

Upgrading MenuSuite Objects
Designing MenuSuite Objects


Upgrading MenuSuite Objects

Upgrading MenuSuite Objects

Menus in a menu suite that are inherited from the previous MenuSuite object level are upgraded when you upgrade the corresponding MenuSuite object. These menus have the >> symbol on the menu button to the left of the menu name. Any changes that you have made to these menus will be merged into the new menu suite when you upgrade. For example, a menu item that you have added to a menu group but where the menu group’s contents now have changed after an upgrade will be placed as the last menu item in the menu group.

Lost Items

There will be cases where a straightforward merge cannot be made. For example, if you have added a menu item to a menu group that is no longer a part of the menu after an upgrade, then no merge can be made. Instead, the menu item will be placed in a Lost Items group at the bottom of the menu tree. Another example would be if you had added one or more menu items to a menu that is no longer present in the menu suite after an upgrade. In such a situation, the menu items will be placed in a Lost Items menu.

After an upgrade, you can take action on the menu items in a Lost Items group or menu—either by inserting them somewhere in another menu or by deleting them. A Lost Items group or menu is not visible in Navigation Pane at runtime.

New Menus

New menus that you have created are not affected by an upgrade. If there are new menu items available after the upgrade that you would like to insert in these menus, you will have to add them manually.

See Also

Tasks

How to: Create and Modify a MenuSuite Object
How to: Customize a MenuSuite Object
How to: Export a MenuSuite Object
How to: Compile a MenuSuite Object

Concepts

Designing MenuSuite Objects


Transforming Forms to Pages

Transforming Forms to Pages

To use the functionality and logic of your existing forms in the RoleTailored client in Microsoft Dynamics NAV 2009, you must first transform the forms into pages. The topics in this section describe how to plan and run form transformations.

Learning about Form Transformation

To | See
Learn about the form transformation process | Understanding Form Transformation
Learn about the form transformation tool | Form Transformation Tool Overview
Learn about what you need to do to prepare to transform forms | Preparing to Transform Forms to Pages

Redesigning Forms

To | See
Understand why you must redesign some forms and which forms to redesign | Preparing for Form Transformation by Redesigning Forms
Redesign forms with matrix-like layout of controls | How to: Redesign Forms with Matrix-Like Layout of Controls
Redesign matrix forms | How to: Redesign Matrix Forms
Redesign journal and worksheet batches | How to: Redesign Journal and Worksheet Batches
Redesign forms with expand and collapse functionality | How to: Redesign Forms with Expand and Collapse Functionality
Redesign list forms for individual document types | How to: Redesign List Forms for Individual Document Types

Transforming Forms

To | See
Transform forms by using the Transformation Input File (TIF) Editor | Preparing Transformation Tool Input
Transform forms by updating the XML input files | Understanding Form Transformation Input Files
Run the form transformation tool | Transforming Forms
Follow step-by-step procedures that show how to perform a transformation of a standard application form | Walkthrough: Transforming a Standard Application Form

Troubleshooting

To | See
Troubleshoot menu items that call subforms | Troubleshooting: Actions That Call Subforms
Troubleshoot the layout of fields in columns | Troubleshooting: Fields in Columns on a Transformed Page
Troubleshoot labels | Troubleshooting: Labels on a Transformed Page
Troubleshoot the layout of lists | Troubleshooting: List Placement on Transformed Pages
Troubleshoot text boxes used as labels | Troubleshooting: Text Boxes Used as Labels on a Transformed Page

Reference

To | See
Learn about Classic client form properties that are used in RoleTailored client pages | Form Property Mapping Rules
Learn about Classic client control properties that are used in RoleTailored client pages | Control Property Mapping Rules
Learn about mapping rules from Classic client form controls to RoleTailored client page controls | Control Mapping Rules
Learn about mapping rules from Classic client form methods to RoleTailored client methods | Method Mapping Rules
Learn about mapping rules from Classic client form triggers to RoleTailored client triggers | Trigger Mapping Rules
View examples of how code rules work and can be rewritten to remove unsupported triggers and methods | Code Rules
View the list of standard application forms that have a matrix-like layout and are redesigned in the Classic client | Redesigned Forms with Matrix-Like Layout
View the list of standard application matrix forms that are redesigned in the Classic client | Redesigned Matrix Forms
Learn about the functions of codeunit 9200, Matrix Management | Codeunit 9200 Matrix Management
View the form types, descriptions, and mapping relationships to page types | Form Type to Page Type Mapping


Understanding Form Transformation

Understanding Form Transformation

In Microsoft Dynamics NAV 2009, the RoleTailored client is the new, rich client and pages are the new way to view, insert, modify, and delete data in the RoleTailored client. The RoleTailored client provides an intuitive and customizable user interface (UI) that you can modify to support the job functions of different work roles in your organization. For more information about pages in the RoleTailored client, see Pages Overview. For more information about the RoleTailored architecture, see RoleTailored Architecture in the Microsoft Dynamics NAV 2009 Installation and Configuring Help.

The RoleTailored client cannot run forms. You must transform your existing forms into pages. By transforming your forms into pages, you can reuse the business layout and logic of your forms. To transform your forms into pages you must use the transformation tool. The topics in this section describe form transformation, the principles behind form transformation, the different methods that you can use to accomplish the transformation from forms to pages, and an overview of the tool that you use to perform form transformation. For more information, see the following:

  • Form Transformation Objectives

  • Form Transformation Principles

  • Form Transformation Methods

  • Form Transformation Tool Overview

The Transformation Process

The following illustration shows the process of transforming forms to pages.

The topics in the Preparing to Transform Forms to Pages section describe the steps you must take before you run the transformation tool. The topics in the Transforming Forms section describe how to use the tool and explain the transformation process in detail.

Additional Steps to Upgrade to Microsoft Dynamics NAV 2009

Before you move to the three-tier architecture, in addition to transforming your forms, you must also do the following:

  • Evaluate your files that reside on the client to determine whether you need to use different functions to upload or download those files. For more information, see Evaluating Client Files and Automation.

  • Evaluate your automation components to determine whether you need to use different functions, change code, or redesign. For more information, see Evaluating Client Files and Automation.

Finally, you may want to redesign your reports to take advantage of the client report definition (RDLC) report layout. You can choose to view your existing Classic report layouts from the RoleTailored client or create new RDLC report layouts. For more information about redesigning reports, see Redesigning Classic Reports with Visual Studio Report Designer.


Form Transformation Objectives

Form Transformation Objectives

Form Transformation enables you to:

  • Transform forms to pages (basic transformation)

  • Tailor resulting pages for the RoleTailored client (UX transformation)

Form-to-page transformation is a basic transformation process that takes form objects from the Microsoft Dynamics NAV Classic application and creates page objects that you can use in the RoleTailored client.

User experience (UX) transformation supplements basic form-to-page transformation by adding additional user interface elements to pages that take advantage of the new user experience in the RoleTailored client.

Basic Transformation

Basic transformation is the conversion of a form, including its existing functionality and business logic, to a new page by mapping the form essentials—properties, controls and code—to the corresponding page components.

The mapping logic is based on rules that are generically applied to all forms. This mapping logic enables you to automate the transformation process. The transformation tool includes built-in mapping rules. In addition to the built-in mapping rules, the transformation input files to the tool include modifiable rules. For more information about the transformation tool and the mapping rules, see Form Transformation Tool Overview.

In addition to replacing existing elements on a form with the corresponding new elements on a page, mapping logic also extends to and includes rules that do the following:

  • Ignore The transformation tool ignores an existing element on a form without replacing it with a corresponding new element on a page. Typically, this occurs in one of the following cases:

    • The RoleTailored client supports the equivalent behavior in a different way than the Classic client.

    • The logic does not require input from the original form.

    • There is not an equivalent element on a page in the RoleTailored client.

  • Add a property The transformation tool adds properties to a page that were not on the original form. For example, PageType is a new page property that is a prerequisite to render a page. CardFormID is another new page property. You must assign a CardFormID to a list form that you will transform to a page. Other properties added to a page through transformation are a part of UX transformation.

The following tables list examples of generic rules that the transformation tool applies automatically during a basic transformation.

Form control | Mapping rule | Page control
TableBox | Replace | Grid (Repeater)
TabControl | Replace | FastTab
Label | In most cases, the CaptionML value of the label is transformed to the CaptionML of the parent or adjacent control. For more information, see Control Mapping Rules. | Caption of field control is used as label.
MatrixBox | Ignore | MatrixBox control is not available.
Form Property | Mapping Rule | Page Property
Width | Ignore | None. Pages and controls have built-in rendering and resizing logic.
XPos | Ignore | None. Pages and controls have built-in rendering and resizing logic.
ParentControl | Ignore | None. Pages and controls have built-in rendering and resizing logic.
ID | Replace | ID
Editable | Replace | Editable
RunObject | Replace | RunObject
ToolTip | Ignore | Not supported
NextControl | Ignore | Not supported
 | Add new | PageType
 | Add new | CardFormID
Code on a Form | Mapping Rule | Code on a Page
Formatting code | Ignore | Replaced with dynamic properties: Editable, Enabled, Visible, and Indentation.
Functionality code - triggers | Replace unsupported triggers by moving code to supported triggers | Supported triggers.
Functionality code - methods | Ignore unsupported methods |

For complete mapping rules, see Form Transformation Reference.

UX Transformation

Through the UX transformation, the automatically generated pages can be tailored to make use of new user interface features in the RoleTailored client. You can either tailor pages through the transformation process or directly in the page object. For more information about the different transformation methods, see Form Transformation Methods. This section describes tailoring pages as part of the transformation process. For more information about designing pages, see Creating and Maintaining Pages.

You can enhance a page as part of a UX transformation in the following ways:

  • Adding FactBoxes and reports to pages.

  • Adding new actions that do not exist on the form.

  • Promoting frequently used actions and reports onto the Action Pane.

  • Assigning icons to actions.

  • Promoting fields to Fast Tab headers.

  • Adding home parts to a role center.

  • Modifying shortcut keys.

For more information about UX transformation, see Specifying Form Transformation Rules with the Transformation Input Files Editor.

The following diagrams illustrate how a form looks before transformation and how the corresponding page looks after transformation.

Sales Order form in Classic client Sales Order page in RoleTailored client

The following changes were made to the sales order task page during UX transformation:

  • Three FactBoxes were added to the right side of the page: Customer Sales History, Sales Line Details, and Notes.

  • Frequently used actions, such as Post, Post and Print, and Release have been added to the Action Pane with the appropriate icons.

  • The Lines FastTab has been placed directly under the General FastTab.

  • Selected fields, such as Customer Bill-to No., Payment Terms Code, and Due Date have been marked with Essential importance so that they appear as a summary on the collapsed Invoicing FastTab.

Unlike basic transformation, UX transformation requires specific instructions for each form. You define these instructions in the transformation input files. For more information about transformation input files, see Understanding Form Transformation Input Files.


Form Transformation Principles

Form Transformation Principles

The form transformation tool was designed with the following principles:

  • The tool converts all existing Microsoft Dynamics NAV forms into pages while retaining the same functionality as the original forms.

  • Basic conversion rules (built into the tool) assume that the user interface and code on the form are compliant with the standard application development guidelines.

  • The tool identifies deviations from the guidelines that may result in missing user interface (UI) elements or functionality of the original form. The tool logs these deviations for manual consideration.

  • If the rules for modifying the page UI are generic to all pages, then the tool incorporates them into the tool mapping logic. The tool regards rules that represent "manual" decisions about certain user experience (UX) behavior, layout, and business logic as additional input. You define this additional input manually.

These principles turn the transformation into a highly automated process that makes the migration path to the new architecture as efficient as possible.

Fully automatic transformation is not possible for the standard global application or for add-ons and customized solutions. This may be caused by the following:

  • Some control types in the Classic client are not available in the same form in the RoleTailored client. For example, the MatrixBox and Shape controls are not supported.

    To generate a page with the same functionality in the RoleTailored client, you have to either replace the original form with an alternate form containing controls that can be transformed, or modify the original form. One of the steps to prepare for form transformation is to redesign forms by either replacing or modifying forms. For more information, see Preparing for Form Transformation by Redesigning Forms.

  • The RoleTailored client has enhanced behavior hard-coded into its controls. Therefore, some code that was necessary in previous versions of Microsoft Dynamics NAV is now obsolete when using the new controls. This means that pages contain fewer triggers than forms. For more information, see Method Mapping Rules.

  • Automation that has no UI and does some kind of processing which includes generating files as output (or consumes files as part of input) requires special consideration. To make this work, you must rewrite C/AL code to properly supply the input or output files needed for the automation. For more information, see Evaluating Client Files and Automation.

  • Automation that uses dialog boxes to display messages or errors requires special consideration. The automation may have its own window (like an OCX) or it may interact with hardware that is local on the client (like a bar code reader or card scanner). These are now unsupported scenarios. Any solution to this problem may require a redesign that functions the same way but takes advantage of Web services, C/FRONT.NET, or another integration technology. For more information, see Evaluating Client Files and Automation.

The more your forms deviate from the design guidelines of the standard application, the more challenging it will be to transform them successfully to pages so that they support the same functionality and are compliant with UX guidelines. For more information about the UX guidelines in Microsoft Dynamics NAV 2009, see User Experience Guidelines for Microsoft Dynamics NAV 2009.

If your goal is to retain one code base in the Classic client and the RoleTailored client, rather than moving all your application development onto the RoleTailored client, you will have to plan for some redesign efforts. For more details, see Preparing for Form Transformation by Redesigning Forms.


Form Transformation Methods

Form Transformation Methods

When you decide to migrate an application to the new three-tiered architecture, you must also decide which migration method is best suited to your business needs. Migrating to the new architecture can be an iterative process. You may need to run the form transformation tool multiple times and carefully alter any problematic forms to ensure that pages can be created that have the required layout. For more information about how to run the transformation tool, see How to: Run the Form Transformation Tool. For more information about how to modify forms, see Preparing for Form Transformation by Redesigning Forms.

It is important to remember that when you transform a form, the form does not change. For each form that you transform, a new page object is created with matching functionality that can be used by the RoleTailored client. You then have two objects—a form and a page. If you run the tool again and transform the same form, the new page object that is created will overwrite the first page object.

If, at a later date, you decide that you want to change the functionality of your application, you can implement the changes in one of the following ways:

  • Implement changes on the form and then transform the form to a page.

  • Implement changes on the corresponding page.

  • Implement changes on both objects, depending on your business needs.

For more information to help you decide how to implement changes, see Developing Applications for the Classic Client and RoleTailored Client.

You can choose between the following methods when you move your application from the Classic client to the RoleTailored client:

  • Reactive Method

  • Proactive Method

  • Start from Scratch Method

  • Combined Method (all of the above)

The method that you choose can vary from one implementation to another. A good development practice is to use a copy of the database to see which method or combination of methods achieves the best results for each implementation.

Reactive Method

The following are the steps for the reactive method:

  1. Run the Transformation Tool. For more information, see How to: Run the Form Transformation Tool.

  2. Check the resulting pages and the log file. For more information, see Reviewing the Form Transformation Log Output File.

  3. Redesign or modify any forms that did not transform successfully. For more information, see Preparing for Form Transformation by Redesigning Forms.

  4. Run the tool again to transform the forms that you have altered.

Proactive Method

The following are the steps for the proactive method:

  1. Redesign any forms that you know will not transform satisfactorily. For more information, see Preparing for Form Transformation by Redesigning Forms.

  2. Run the Transformation Tool. For more information, see How to: Run the Form Transformation Tool.

  3. Check the resulting pages and the log file. For more information, see Reviewing the Form Transformation Log Output File.

  4. Modify forms that are still causing problems.

Start from Scratch Method

The following are the steps for the start from scratch method:

  • Implement your entire application in the Page Designer and ignore the transformation tool. For more information, see Creating and Maintaining Pages.

Combined Method

The following are the steps for the combined method:

  1. Transform some forms to pages.

  2. If desired, modify the resulting pages in Page Designer to get greater benefit from the new user experience (UX). For more information about Page Designer, see Creating and Maintaining Pages.

  3. If desired, create some new pages without transforming the source forms.


Form Transformation Tool Overview

Form Transformation Tool Overview

The Transformation Tool converts form objects in the Classic client to page objects that you can use in the RoleTailored client. The tool uses a set of rules that map objects in the Classic client to objects in the RoleTailored client. These rules are contained both in the transformation input files and in the transformation tool source files. In addition to the transformation input files, which specify the modifiable rules for transformation, the transformation tool uses schema files, a configuration file, and a coderules file to transform the source forms in the forms.xml file into pages. The transformation tool creates a pages.xml file, which contains the pages that you can view in the RoleTailored client, and a log output file.

The following illustration shows the form transformation framework and how the transformation tool fits into that framework.

diagram of transformation tool, inputs and outputs

As this illustration shows, transforming forms is an iterative process. You may need to run the transformation tool more than once on a given form to create a page with the functionality that you want. After you run the tool and view the transformed page, you may want to modify some of the rules that the tool uses and produce different page functionality or modify the user interface (UI) for the page. You change the rules by modifying the transformation input files. You can modify these files directly or you can use the Transformation Input Files (TIF) Editor to modify input files.

Rules

The set of rules that the transformation tool uses can be divided into three categories:

  • Generic, built-in rules that are applicable to all forms.

  • Generic, modifiable rules that are applicable to all forms.

  • Non-generic, modifiable rules that are applicable to individual forms.

Built-in rules are part of the transformation tool itself. Modifiable rules are input to the tool in the transformation input files.

Generic, Built-In Rules

Most transformation tool rules are used for basic form to page transformations, and are related to controls and properties. These rules ensure that the generated pages contain the same functionality as the original forms. Additionally, there are some rules that specify user interface (UI) behavior that is universal across all pages. For example, a table is always placed second in the control hierarchy of a page, which means that the Lines FastTab appears after the General FastTab and before other FastTabs. For more information about FastTabs, see Touring the RoleTailored Client Pages.

All rules in this category are built into the logic of the transformation tool. You cannot change these rules without modifying the source files.

Generic, Modifiable Rules

Some transformation rules are specified manually. These rules can be modified and are applied by the tool to all form objects. Examples of generic, manually-specified rules are the following:

  • Mapping triggers and methods

  • Mapping existing shortcuts

  • Adding new shortcuts

  • Promoting selected commands based on caption (rather than control ID)

  • Assigning icons to commands

These rules are contained in input files to the tool, and are applied when you run the tool. To modify these rules, you either use the TIF Editor or modify the transformation input .xml files directly. For more information about modifying the transformation input files, see the following topics:

  • Understanding Form Transformation Input Files

  • Specifying Form Transformation Rules with the Transformation Input Files Editor

Non-generic, Modifiable Rules

Some rules are applicable to individual forms, not to the set of all forms. Two of these non-generic rules are required. All other rules in this category are optional and can be applied to pages that you want to modify. The required rules are the following:

  • Assigning appropriate PageType properties to all pages.

  • Assigning appropriate CardFormID properties to list pages.

Examples of optional, non-generic rules are the following:

  • Ignoring specific pages

  • Ignoring specific controls

  • Replacing one form with another (applicable if a redesigned form is a new form). For more information about replacing one form with another, see Preparing for Form Transformation by Redesigning Forms.

All rules in this category are specified manually and therefore, can be modified. Similar to the generic, modifiable rules, these rules are contained in input files to the tool, and are applied when you run the tool. To modify these rules, you either use the TIF Editor or modify the transformation input .xml files directly. For more information about modifying the transformation input files, see the following topics:

  • Understanding Form Transformation Input Files

  • Specifying Form Transformation Rules with the Transformation Input Files Editor

Input

The transformation tool uses the following input:

  • Forms.xml - All forms that you want to transform, exported as XML files from the Classic client. For more information, see How to: Create the Forms.xml Source File.

  • CodeRules.txt – A set of rules that, through code pattern recognition, maps triggers and methods. For more information, see Code Rules.

  • Transformation input files. For more information, see Understanding Form Transformation Input Files. The transformation input files are the following:

    • TransformPages.xml

    • MoveElements.xml

    • MovePages.xml

    • IgnorePages.xml

    • DeleteElements.xml

  • Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config – An editable configuration file that provides the location of input and output files and defines the scope of logging. For more information, see Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File.

  • XML schema files

Output

The transformation tool produces the following output:

  • Pages.xml - Pages that can be displayed in the RoleTailored client.

  • Transformation.log – A file that logs progress information while the tool runs and provides information about issues detected by the tool. After you run the tool, inspect the log file to determine if you need to make changes to the input and run the transformation again. Use the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file to configure the output in the log file.

For more information about how to import and compile the pages in pages.xml, and how to view the new pages in the RoleTailored client, see How to: Import, Compile, and Run Transformed Pages.

For more information about the types of information in the log file and how to use the log file, see Reviewing the Form Transformation Log Output File.

See Also

Concepts

Form Transformation Reference


Transforming Control and Menu IDs

Transforming Control and Menu IDs

When you transform a form to a page, the transformation tool generally applies a one-to-one mapping between form control and menu IDs on a form and page control and action IDs on a page. A control on a transformed page has the same ID as the corresponding control on the source form.

However, in the following cases, the controls and menu items are assigned a new ID by the transformation tool:

  • If one-to-one mapping of controls or menu items is not possible. For example, you may have mapped one tab control on a form to multiple FastTab controls on a page.

  • If new controls or actions have been added to the page that do not originate from the source form. For example, you may have added a FactBox to a page by using transformation input.

  • If controls exist on the source form that are moved to a different page when transformed. For example, you may have specified that a menu item on a main form calls a subform. It is then transformed to an action on a subpage instead of on the main page.

The new automatically generated IDs are assigned based on a hash algorithm that uses the ENU caption of the control or menu item.

Note Note

This topic applies only to Microsoft Dynamics NAV 2009 SP1. For more information about the hotfix for the RTM version of Microsoft Dynamics NAV 2009, see Hotfix for Microsoft Dynamics NAV 2009: Control and Action ID Assignments on PartnerSource.

Example

An application has a form with ID=10. The TabControl with ID=1 specifies three tabs in the PageNames Property. The tabs on the form are:

  • General

  • Invoicing

  • Shipping

When you transform the form to a page, the tabs are transformed to three controls of Type=Group (FastTabs). The following table shows the automatically generated control IDs of the FastTabs.

Control | ID
General FastTab | 1
Invoicing FastTab | 1905885101
Shipping FastTab | 1906801201

Now, you modify the source form to include an additional tab, "Communication." The tabs now are:

  • General

  • Communication

  • Invoicing

  • Shipping

When you retransform the form, the new page has four FastTab controls. The original three FastTabs have the same control IDs as they had when you transformed the form to a page the first time. The new FastTab has a control ID that is based on its ENU caption. The following table shows the control IDs of the FastTabs.

Control | ID
General FastTab | 1
Communication FastTab | 1902768801
Invoicing FastTab | 1905885101
Shipping FastTab | 1906801201

Assigning Control and Action IDs

You can also specify control and action IDs for the transformed page. You may want to identify all objects, fields, and controls that you create by assigning IDs within a given range. In that case, you can assign specific control and action IDs instead of allowing the transformation tool to assign IDs automatically. Controls and menu items for which you do not specify an ID will be assigned a unique ID based on the hash algorithm.

For more information about assigning control IDs, see the following topics:

  • How to: Specify TabControl IDs By Using Transformation Input

  • How to: Add Actions to a Page By Using Transformation Input

  • How to: Add FactBoxes to Pages By Using Transformation Input

  • How to: Add Home Parts to a Role Center By Using Transformation Input

  • Understanding Form Transformation Input Files

See Also

Concepts

Understanding Form Transformation


Preparing to Transform Forms to Pages

Preparing to Transform Forms to Pages

The transformation process has two stages:

  • Preparing for transformation

  • Transforming forms

The following diagram illustrates the process of transforming forms to pages.

The topics in this section provide an overview of the steps that you need to take to prepare for transformation.

If you take the time to prepare your forms for transformation, the transformation will be more efficient and complete.

To prepare for transformation, you need to perform the following steps:

  1. Install the form transformation tool. For more information, see How to: Install the Form Transformation Tool.

  2. Redesign existing forms in the Classic client. It is not possible to transform some forms, such as Matrix forms. Redesigning forms smoothes the transformation process and helps to minimize errors when you run the tool and layout issues in the transformed page. For more information, see Preparing for Form Transformation by Redesigning Forms.

  3. Define the transformation input. Create mapping specifications by using the Transformation Input Files (TIF) Editor or by directly modifying the transformation input .xml files. You must assign each page a type. You can also specify additional layout and user experience (UX) changes. For more information, see Preparing Transformation Tool Input.


How to: Install the Form Transformation Tool

How to: Install the Form Transformation Tool

You must copy the form transformation tool files before you can transform forms. The files that you must copy are located in the TransformationTool folder and the TransformationTool\TIF Editor folder on the installation DVD.

The TransformationTool folder contains several files, including the .xml transformation input files. For more information about the transformation input files, see Understanding Form Transformation Input Files. The TIF Editor folder contains the TIF.fob and FormToPagetypeMapping.txt files.

Before you begin this procedure, confirm the following:

  • You have Microsoft Dynamics NAV 2009 installed with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements are met. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements in Microsoft Dynamics NAV 2009 Installation and Configuration Help.

To install the form transformation tool

  • Copy the contents of the TransformationTool folder, which includes the TIF Editor folder, from the installation DVD. You can copy these to any location on the Microsoft Dynamics NAV 2009 server.


Preparing for Form Transformation by Redesigning Forms

Preparing for Form Transformation by Redesigning Forms

You may need to redesign some of your forms to make them preserve the business logic and layout when you transform the form to a page. Redesigning means that you have to either create a new form to replace the one that cannot be transformed, or modify the original form. Usually you only need to redesign a few forms in your application.

Why Redesign Your Forms?

The following reasons may be why you may need to redesign some of your existing forms:

  • Unsupported controls

  • Matrix-like layouts do not transform successfully

  • New user experience (UX) guidelines

Unsupported Controls

The RoleTailored client does not support certain control types that are used in the Classic client. The unsupported controls are the following:

  • MatrixBox

  • Shape

You cannot map these controls in the Classic client to controls in the RoleTailored client. If a form contains one of these types of controls, then it will not transform. Matrix forms are examples of forms that use these types of controls. You must start at the beginning and design a new form.

Matrix-Like Layout

Certain controls, when used together, create a matrix-like layout. Although the individual controls are supported, the matrix-like layout will not transform successfully. You must redesign forms with a matrix-like layout.

New UX Guidelines

The RoleTailored client has new navigation principles and UX guidelines. This means that you must modify the behavior of some Classic client forms before they can be transformed, for example:

  • In the RoleTailored client, the user must always be able to move from a list place to a card.

  • In the RoleTailored client, Journal forms must connect to their respective batch lists

  • In the RoleTailored client, separate list forms must be created for each document type.

Some forms in the standard application were redesigned to new forms for UX improvements. The following table shows these forms.

Original form | Redesigned form | Description of change
Form 6512, Item Tracking Code Card | Form 9368, _Item Tracking Code Card | All check boxes are in one column.
Form 402, Sales Order Statistics | Form 9402, _Sales Order Statistics | The tables at the bottom of each tab were removed.
Form 403, Purchase Order Statistics | Form 9403, _Purchase Order Statistics | The tables at the bottom of each tab were removed.
Form 5914, Service Order Statistics | Form 9404, _Service Order Statistics | The tables at the bottom of each tab were removed.
Form 7002, Sales Prices | Form 9420, _Sales Prices | The Currency Code Filter drop-down list is moved to the General tab so that there is only one tab on the form instead of two.
Form 7004, Sales Line Discounts | 9421, _Sales Line Discounts | The Currency Code Filter drop-down list is moved to the General tab so that there is only one tab on the form instead of two.

Several advanced confirmation forms in the standard application were redesigned so that they transform to pages successfully. The following table shows these forms.

Form ID | Form name
342 | Check Availability
343 | Check Credit Limit
476 | Copy Tax Setup
511 | Change Exchange Rate
579 | Post Application
591 | Payment Tolerance Warning
692 | Import Style Sheet
695 | Confirm Financial Void
722 | BA Password Entry
802 | Online Map Address Selector
5135 | Customer Link
5136 | Vendor Link
5137 | Bank Account Link
5142 | Save Segment Criteria
5526 | Make Supply Orders
5985 | Service Item Replacement
6002 | Cancelled Allocation Reasons
6022 | Reallocation Entry Reasons
6024 | Reallocation Entry Reasons
6079 | Contract Amount Distribution
6513 | Enter Quantity to Create
6515 | Enter Customized SN
8622 | Company Setup
99000833 | Check Prod. Order Status
99000882 | Change Status on Prod. Order
99000884 | Create Order From Sales
99000901 | Check Date Conflict

Redesigned Forms in Microsoft Dynamics NAV 2009

Several forms in the Microsoft Dynamics NAV 2009 standard application have been redesigned. The following topics list the redesigned forms in the standard application:

  • Redesigned Forms with Matrix-Like Layout

  • Redesigned Matrix Forms

The following topics describe how to redesign the various types of forms that cannot be successfully transformed:

  • How to: Redesign Forms with Matrix-Like Layout of Controls

  • How to: Redesign Matrix Forms

  • How to: Redesign Journal and Worksheet Batches

  • How to: Redesign Forms with Expand and Collapse Functionality

  • How to: Redesign List Forms for Individual Document Types

You can use the information in these topics in the following ways:

  • If your forms have the same pattern as the forms in these topics, redesign your forms in the same manner.

  • If your forms do not have the same pattern as the forms in these topics, use the changes that are described to offer insight into alternative redesign solutions for your specific forms.


How to: Redesign Forms with Matrix-Like Layout of Controls

How to: Redesign Forms with Matrix-Like Layout of Controls

Certain controls, when used together, create a matrix-like layout. Although the individual controls are supported, the matrix-like layout will not transform successfully. Before you transform forms with a matrix-like layout of controls, you must redesign these forms in the Classic client Form Designer to ensure that fields on the transformed page are displayed in the same matrix-like layout as on the original form.

The RoleTailored client has the following requirements for forms that you want to transform:

  • All cells in a matrix-like layout must contain a value.

  • A control in the second column must have a row header that is a CaptionML. For example, in Form 151, Customer Statistics, this is the column with header January.

  • Fields in a matrix-like layout must be in individual control containers, such as TabControls or Frames.

  • The first row, which displays column headers, must be assigned the FixedLayout property. Only label controls can have the FixedLayout property.

Statistics forms are an example of forms with a matrix-like layout that display fields in more than one column. The following illustration shows a statistics form in the standard application, Form 151, Customer Statistics.

Form 151, Customer Statistics, does not comply with the second or third requirements for forms that you want to transform. The second column has a row header that is a calculated text box. In addition, in the first row with column headers, Form 151 has both a calculated text box control (with SourceExpr=CustDateName) and label controls.

This form has been redesigned in Microsoft Dynamics NAV 2009 so that the second column header is a label with CaptionML="This Period" instead of the original calculated text box. The first row with column headers contains only labels, to which you can apply the FixedLayout option. The form has also been redesigned to include a second row for the calculated text box, SourceExpr=CustDateName. In the other columns in this new row, the form is redesigned to include placeholder controls so that the form complies with the first requirement.

The following illustration shows the transformed page if you first redesign the form, as described in this topic, and then transform the form.

Another example of a form in the standard application with a matrix-like layout that you must redesign and apply the fixed layout property is form 6510, Item Tracking Lines.

An example of a form in the standard application to which you must apply the fixed layout property is form 39, General Journal.

Redesigning a Form with a Matrix-Like Layout of Controls

To redesign a form with a matrix-like layout of controls

  1. Determine which of the four requirements with which the form does not comply.

  2. Click the Tools menu, and then click Object Designer. In Object Designer, select Form, select the form that you want to transform, and then click Design.

  3. If the form does not comply with the requirement that all cells in the matrix-like layout must contain a value, then you must create a placeholder value in any cell that you want to leave blank. To create a placeholder value, we recommend that you set the properties of the cell to the following values:

    • Control := TextBox

    • SourceExpr := Text000 (where Text000 is defined as a global text constant with the value "Placeholder."

    • ForeColor = 65535 (Yellow, to mark the placeholder)

    • Visible = No

    To create the placeholder with these values, do the following:

    1. Create a text box. For more information about how to create a text box, see How to: Add a Text Box.

    2. Right-click the new text box and then select Properties.

    3. In the TextBox - Properties window, find the Visible property. In the Value column, select No from the drop-down list.

    4. In the TextBox - Properties window, find the ForeColor property. In the Value column, enter 65535.

    5. From the View menu, select C/AL Globals. In the TextBox - C/AL Globals window, select the Text Constants tab. Add a new text constant. The Name of the text constant is Text000 and the Value is Placeholder.

    6. In the TextBox - Properties window, find the SourceExpr property. In the Value column, enter Text000.

  4. If the form does not comply with the requirement that a control in the second column must have a row header that is a label with the CaptionML property defined, then you must modify the row header. To modify the row header, do the following:

    1. Delete the existing row header and create a label for the new row header. For more information about how to create a label, see How to: Create Labels.

    2. Right-click the new label and then select Properties.

    3. In the TextBox - Properties window, set the CaptionML property.

  5. If the form does not comply with the requirement that controls in the first row, which are column headers, must be label controls so that you can assign the FixedLayout property, then you must modify the column headers in the first row. To modify the column headers, do the following:

    1. If any of the column headers are not label controls, delete the controls and add labels. For more information, see How to: Create Labels.

    2. Right-click the new label and then select Properties.

    3. In the TextBox - Properties window, set the CaptionML property.

  6. If the form does not comply with the requirement that the first row must be assigned the FixedLayout property, then set the FixedLayout property by using the Transformation Input File (TIF) Editor. For more information, see How to: Set the FixedLayout Property.

  7. Move each matrix-like layout to a separate container so that the form complies with the requirement that fields in a matrix-like layout must be in individual containers. To do this, you must create new containers, such as a TabControls or Frames, and then use Form Designer to add a single matrix-like layout to each container. For more information, see the following topics:

    • How to: Create a Frame to Contain Controls

    • How to: Create a Tab Control

    The following illustrations show form 151, Customer Statistics, in Form Designer, before and after redesign.

  8. To save and compile your form, close the form in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

See Also

Concepts

Redesigned Forms with Matrix-Like Layout
Arranging Fields in Rows and Columns Using a FixedLayout Control


How to: Redesign Matrix Forms

How to: Redesign Matrix Forms

The matrix box control is not supported by the RoleTailored client. Therefore, to create the same matrix layout and functionality on a transformed page, you must design a new form to replace the original matrix form.

In a matrix form, the table is a matrix box control, which is different from a table box control that has a finite number of rows and columns. A matrix box brings in data from two tables in the database and displays one set of data as lines and one set of data as columns. The matrix box calculates values using the data from the two tables. Each cell in the matrix represents an intersection of the two tables. For example, in form 554, Analysis by Dimensions, the table shows account information and date information from different tables and calculates a value based on the account data on a given date. In the matrix table, you can scroll through an infinite set of dates to view the calculated values.

In the RoleTailored client, because matrix box controls are not supported, you must display the information in a table that has a finite number of columns. To achieve the matrix behavior, you must allow the user to change the columns and filters, and you must refresh the data in the table with each change.

You cannot use the transformation tool to transform a matrix form into a page. Instead, you must create a form to replace the matrix form. The new form has the following characteristics:

  • One or more tabs with the filters from the original form.

  • Controls for selecting the next or previous column.

  • Controls for selecting the next or previous set of columns.

  • Controls for selecting the next or previous period. This is only required if this functionality is on the original form.

  • A table box control that shows the data that is selected by the options, filters, and controls.

If you isolate the matrix table on a subform instead of including a table box on the main form, then you can use the functions in codeunit 9200 to manage the behavior of the new matrix forms. For more information about the content of codeunit 9200, see Codeunit 9200 Matrix Management.

The following illustration shows form 113, Budget, before redesign.

Matrix Form 113, Budget

The following illustration shows the redesigned form.

Redesigned form 9202, Budget

To create the new form

  1. On the Tools menu, click Object Designer.

  2. In Object Designer, select the form that you want to replace, and then click Design.

  3. On the File menu, click Save As to save the form with the new form ID.

  4. In Form Designer, select the Matrix Box control, and then on the Edit menu, click Delete.

  5. In Form Designer, add a Table Box control. For more information, see How to: Create a Table Box.

  6. On the View menu, click Field Menu.

  7. In the Field Menu, select the fields that were in the left columns of the original matrix form.

  8. Add additional TextBox controls to the table for the additional columns that you want in your new table. These columns replace the matrix columns on the right of the original matrix form.

  9. Define two array variables:

    • A Text array variable for the column captions, such as MyColumnCaptions

    • An array variable, typically Decimal, for the calculated values of a line, such as MyColumnValues

  10. Specify the value of the SourceExpr property of the new TextBox controls as MyColumnValues[ColumnNumber]. Specify the value of the CaptionClass property as '3,'+MyColumnCaptions[ColumnNumber] where ColumnNumber is 1 for the first column, 2 for the second column, and so on. You must add code to the OnAfterGetRecord form trigger to calculate each cell value and column header.

    Note Note

    Use the matrix box on the original form, the C/AL code on that matrix box, and the redesigned matrix forms in the standard application as guidance for creating this table. For more information about the redesigned matrix forms, see Redesigned Matrix Forms.

  11. Redesign the code on the form as necessary to ensure that the functionality on the redesigned form works as expected

    Note Note

    Each form is different, so you must evaluate the code on each matrix form individually. Use a page or a redesigned form that is similar to the matrix form for guidance when redesigning.

  12. On the File menu, click Save.. Confirm that the Compile check box is selected, and then click OK.

See Also

Tasks

Walkthrough: Redesigning the Acc. Schedule Overview Form


How to: Redesign Journal and Worksheet Batches

How to: Redesign Journal and Worksheet Batches

In the RoleTailored client, the navigation principle that a user must always be able to move from a list place to a card also applies to journals and worksheets. The user navigates from a list of several batches to a specific journal or worksheet. This method is not required in the Classic client, so you must modify C/AL code prior to transformation.

The following figure shows an example of a journal form that was redesigned in Microsoft Dynamics NAV 2009 so that it can be transformed to a page. This form, form 251, General Journal Batches, contains a list of batches of Cash Receipt journals.

To follow the navigation principle in the RoleTailored client, you must redesign your journal and worksheet batches.

To redesign journal and worksheet batches

  1. Click the Tools menu, and then click Object Designer.

  2. In Object Designer, select Table, select the table on which the journal form that you want to redesign is based, and then click Design.

  3. In Table Designer, add the following fields to the table:

    • Template Type (Data type: Option)

    • Recurring (Data type: Boolean)

    For an example of a table with these fields, see Table 232, Gen. Journal Batch.

  4. In Object Designer, select Codeunit, and then select the journal management (…JnlManagement) codeunit for the journal or worksheet batch that you are redesigning. Add the following methods to the codeunit:

    • PROCEDURE TemplateSelectionFromBatch

    • PROCEDURE OpenJnl

    For examples of these procedures, see Codeunit 230, GenJnlManagement.

  5. In the journal management codeunit, add an If OpenFromBatch condition to the TemplateSelection procedure. For an example of the If OpenFromBatch condition, see the TemplateSelection procedure in Codeunit 230

  6. In Object Designer, select Form, select the journal or worksheet batch form that you are redesigning, and then click Design.

  7. In Form Designer, add a command button labeled Edit Journal to the journal batch form. When you click the new command button, the journal opens. For more information about how to add a command button, see How to: Create Command Buttons.

    For an example, see Form 251, General Journal Batches.

  8. In Form Designer, click the View menu, and then select C/AL Code. In the C/AL Editor, add code to the OnInit and OnOpenForm triggers. For examples of the code to add, see Form 251, General Journal Batches.

  9. In Object Designer, select Form, select the journal form (not the journal batch form), and then click Design. Click the View menu, and then select C/AL Code.

  10. In the C/AL Editor, add code to the OnOpenForm trigger. The added code is contained within the OpenFromBatch condition.

    For an example of the code on the OnOpenForm trigger, see Form 39, General Journal.


How to: Redesign Forms with Expand and Collapse Functionality

How to: Redesign Forms with Expand and Collapse Functionality

Some forms have a list layout with hierarchy. On these forms, not all lines in the list have the same level in the hierarchy. Subordinate lines may be indented, or may be grouped so that you can expand and collapse the group. If you want to transform a form with a hierarchical list and with expand and collapse functionality, you must modify the C/AL code in the OnOpenForm trigger so that all the lines are expanded. The RoleTailored client must have all lines expanded so access is available to all lines to determine which lines to indent and by how much. If you do not modify the code, the transformed page will not work correctly.

Some examples of forms in the standard application that have hierarchical lists and have expand and collapse functionality are the following:

  • Form 5522, Order Planning

  • Form 5847, Average Cost Calc. Overview

  • Form 6520, Item Tracing

For more information, see OnOpenForm Trigger.

To redesign a form with expand and collapse functionality

  1. Click the Tools menu, and then click Object Designer.

  2. In Object Designer, select Form, select the form that you want to transform, and then click Design.

  3. Click the View menu, and then click C/AL Code.

  4. In the Form - OnOpenForm section, add the following code.

    CopyCode image Copy Code
    IF ISSERVICETIER THEN
 ExpandAll
ELSE
 InitTempTable

  5. To save and compile your form, close the form in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.


How to: Redesign List Forms for Individual Document Types

How to: Redesign List Forms for Individual Document Types

The RoleTailored client does not support pages that are created by filtering the page view based on the document type. For example, in the Classic client, when you view form 42, Sales Order, the form view is the result of filtering the source table for documents whose type is Order. Before you transform forms to pages, if you have list forms that refer to the same source table and display a filtered set of records from that source table, you should redesign the list forms into separate list views. You do this by creating individual forms for each filtered view. Lists that you must split into separate list forms are typically those that relate to documents and analysis views, such as Sales List, Purchase List, Service List, Registered Warehouse Receipts, and Analysis Reports.

This topic describes how to create a new list form for each filter by copying the original list and than changing the SourceTableview property from WHERE(Document Type=FILTER(<the given doc type or domain area>)) to WHERE(Document Type=CONST(<the given doc type or domain area>)).

The following illustration shows the six separate, redesigned list forms in Object Designer that are each based on the same source table as the Sales List form.

To redesign a list form for individual document types

  1. In the Classic client, click the Tools menu, and then click Object Designer.

  2. In Object Designer, click Form, and then click New.

  3. In the New Form window, in the Table drop-down list, select the table on which the list form that you are redesigning is based.

  4. In the New Form window, under Form, select Create a form using a wizard, select Tabular-type form, and then click OK.

  5. In the Tabular-type Form Wizard, select the fields that you want to include on the form, and then click Finish.

  6. Close Form Designer. In the dialog box, click Yes to save changes to the form.

  7. In the Save As window, enter an ID and a Name for the new form. Confirm that the Compiled check box is selected, and then click OK.

  8. In Object Designer, select the form that you created, and then click Design.

  9. Click the View menu and then click Properties.

  10. In the Properties window, copy the values from the list form that you are redesigning.

  11. In the SourceTableView field, enter the following value:

    WHERE(Document Type=CONST( <document type or domain area> ))

    For example, if you are redesigning the Sales Quote List, the SourceTableView field is the following:

    WHERE(Document Type=CONST(Quote))

  12. Repeat steps 2 through 11 for each filtered list that you want to create.


Walkthrough: Redesigning the Acc. Schedule Overview Form

Walkthrough: Redesigning the Acc. Schedule Overview Form

The following walkthrough demonstrates the process of redesigning a matrix form so that it uses a table box control instead of a matrix box control. The matrix box control is not supported on the RoleTailored client, and you cannot transform a form with a matrix box control to a page by using the form transformation tool. You must redesign the matrix form and then transform the redesigned form to a page.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating a copy of the original matrix form and saving the copy as the redesigned form.

  • Replacing the matrix box control with a table box control on the redesigned form.

  • Modifying controls on the form that work with the table box.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

Expand image Story

Viktor is a Microsoft Certified Partner who is working with CRONUS International to transform their forms to pages in Microsoft Dynamics NAV 2009 SP1. CRONUS International has several forms that use matrix box controls, and Viktor knows that he must redesign these forms before he can transform them to pages. He has looked at the redesigned matrix forms in Microsoft Dynamics NAV 2009 SP1, which are listed in the Redesigned Matrix Forms topic. He is familiar with how these forms were redesigned and is now ready to redesign form 490, Acc. Schedule Overview.

Expand image Redesigning the Acc. Schedule Overview Form

The first step for Viktor is to make a copy of the original matrix form so that he does not lose any code or functionality on the original form and can refer to the original form as he redesigns the copy.

To copy the original matrix form

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Form, select form 490, Acc. Schedule Overview, and then click Design.

  3. One the File menu, click Save As.

  4. In the Save As window, in the ID field, enter 50490. In the Name field, enter New Acc. Schedule Overview, and then click OK.

Viktor must remove the matrix box control from the form and replace it with a table box control. He must then add columns to the table and specify the values for the matrix-like columns in the table. To do that, he must create an array variable for the column values and an array variable for the column headers.

To replace the matrix box with a table box

  1. In Form Designer for form 50490, delete the matrix box control. Right-click the top left corner of the Matrix Box, and then click Cut.

  2. Create a Table Box on the form. For more information, see How to: Create a Table Box.

  3. On the View menu, click Field Menu.

  4. In the Field Menu, select both the Row No. and Description lines, click the form, and then click the table box to add these fields to the table.

  5. Add 12 additional columns to the table. To add a column, add a Text Box control to the table. For more information, see How to: Add a Text Box without Using the Field Menu.

  6. On the View menu, click C/AL Globals.

  7. On the Variables tab, add a new variable by doing the following:

    1. In the Name field, enter ColumnValues.

    2. In the DataType field, select Decimal.

  8. To specify that the ColumnValues variable is an array, do the following:

    1. On the View menu, click Properties.

    2. In the ColumnValues - Properties window, in the Dimensions field, enter 12.

  9. In the C/AL Globals window, on the Variables tab, add a new variable by doing the following:

    1. In the Name field, enter ColumnCaptions.

    2. In the DataType field, select Text.

  10. To specify that the ColumnCaptions variable is an array, do the following:

    1. On the View menu, click Properties.

    2. In the ColumnCaptions - Properties window, in the Dimensions field, enter 12.

  11. In each of the 12 additional columns, do the following:

    1. Select the column, and then on the View menu, click Properties.

    2. In the SourceExpr property, enter ColumnValues[<column number>] where <column number> is the number of the column from 1 to 12.

    3. In the CaptionClass property, enter '3,'+ColumnCaptions[<column number>] where <column number> is the number of the column from 1 to 12. For more information about this value, see CaptionClass Syntax.

  12. In Form Designer, select the form, and then on the View menu, click C/AL Code.

  13. Modify the lines of code that use CurrForm.AccSchedMatrix.MatrixRec to use TempColumnLayout instead. For example, in the OnOpenForm function, change

    CopyCode image Copy Code
    AccSchedManagement.OpenColumns(CurrentColumnName,CurrForm.AccSchedMatrix.MatrixRec);

    to

    CopyCode image Copy Code
    AccSchedManagement.OpenColumns(CurrentColumnName,TempColumnLayout);

    The CurrForm.AccSchedMatrix.MatrixRec is used in the following functions:

    • OnOpenForm trigger

    • OnAfterValidate trigger of the CurrentScheduleName text box

    • OnAfterValidate trigger of the CurrentColumnName text box

    The reason for this change is that in the original form, the CurrForm.<matrix box control name>.MatrixRec contained the column table. In the redesigned form, there is no matrix box control. You use the temporary TempColumnLayout table instead. TempColumnLayout contains the column table.

  14. In the Form - C/AL Editor window, add the following code to the OnOpenForm trigger.

    CopyCode image Copy Code
    UpdateColumnCaptions;

    This calls a function, which you add later in this walkthrough, to update the column captions when the form opens. Later in this walkthrough, you also call this function in the OnPush trigger of two new command buttons.

  15. In the Form - C/AL Editor window, add the following code to the OnAfterGetRecord trigger to set the values of the cells.

    CopyCode image Copy Code
    IF Totaling = '' THEN
  CLEAR(ColumnValues)
ELSE
  IF TempColumnLayout.FINDSET THEN
    REPEAT
      ColumnNo := ColumnNo + 1;
      IF (ColumnNo > ColumnOffset) AND
        (ColumnNo - ColumnOffset <= ARRAYLEN(ColumnValues)) THEN BEGIN
        ColumnValues[ColumnNo - ColumnOffset] :=
          AccSchedManagement.CalcCell(Rec,TempColumnLayout,UseAmtsInAddCurr);
        ColumnLayoutArr[ColumnNo - ColumnOffset] := TempColumnLayout;
      END;
    UNTIL TempColumnLayout.NEXT = 0;

  16. With the cursor in the OnAfterGetRecord trigger, on the View menu, click C/AL Locals.

  17. In the Form - OnAfterGetRecord - C/AL Locals window, on the Variables tab, enter a new variable by doing the following:

    1. In the Name field, enter ColumnNo.

    2. In the DataType field, select Integer.

  18. On the View menu, click C/AL Globals.

  19. In the C/AL Globals window, enter a new array variable by doing the following:

    1. In the Name field, enter ColumnLayoutArr.

    2. In the DataType field, select Record.

    3. In the Subtype field, enter Column Layout.

    4. On the View menu, click Properties.

    5. In the Properties window, in the Dimensions field, enter 12.

Next, Viktor deletes the controls that he no longer needs, adds new controls to work with the table box, and rearranges controls to improve the layout of the form.

To arrange controls

  1. In Form Designer, on the General tab, select the Previous Period and Next Period command button controls from the bottom of the form and move them to the top section near the text boxes.

  2. On the General tab, delete the following controls:

    • Date Filter label

    • Date Filter text box

    • Budget Filter label

    • Budget Filter text box

    These filters are available on the transformed page.

    Note Note

    To view the filters on the transformed page, in the top right corner of the page, click the Customize button, and then select Limit Totals To.

  3. On the Options tab, select both the Show Amounts in Add. Reporting Currency check box control and label, right-click the selection, and then click Cut.

  4. On the General tab, right-click the section in which the text boxes are located, and then click Paste.

  5. On the Options tab, right-click the Show Error text box, and then click Cut.

  6. On the Options tab, right-click the Show Error label, and then click Cut.

  7. Delete the Options tab. To do this:

    1. Select the tab control, and then on the View menu, click Properties.

    2. In the Properties window, in the PageNames property, delete Options from the value. The resulting value of the PageNames property is General, Dimension Filters.

  8. Instead of the OptionButton controls at the bottom of the form that specify the period, add a text box to the top section of the General tab. To do this:

    1. On the View menu, click Toolbox.

    2. In the Toolbox, select the Text Box icon.

    3. In the Toolbox, select the Add Label icon.

    4. In Form Designer, click and drag to add a text box with a label.

    5. Select the text box, and then on the View menu, click Properties.

    6. In the Properties window, in the SourceExpr property, enter PeriodType. PeriodType is an Option variable and is the source expression for the OptionButton controls on the original form.

    7. In the Caption property, enter View by.

    8. Delete the option button controls at the bottom of the form.

    9. Add code to the OnValidate trigger of the PeriodType text box. Copy the code from another matrix form that has been redesigned, such as form 9202, _Budget. The following code is from the OnValidate trigger in form 9202, _Budget.

      CopyCode image Copy Code
      FindPeriod('');

  9. Resize the section and arrange the controls as necessary.

  10. Add Previous Column and Next Column command button controls. Copy these controls from another matrix form that has been redesigned, such as form 9202, _Budget, and then update the code. To update the code, do the following:

    1. Select the Previous Column command button control, and then on the View menu, click C/AL Code.

    2. In the OnPush trigger, delete the existing code and add the following.

      CopyCode image Copy Code
      AdjustColumnOffset(-1);

    3. Select the Next Column command button control, and then on the View menu, click C/AL Code.

    4. In the OnPush trigger, delete the existing code and add the following.

      CopyCode image Copy Code
      AdjustColumnOffset(1);

    5. On the View menu, click C/AL Globals.

    6. On the Functions tab, on a new line, enter AdjustColumnOffset, and then click Locals.

    7. In the AdustColumnOffset - C/AL Locals window, on the Parameters tab, add a parameter. In the Name field, enter Delta. In the DataType field, select Integer.

    8. In the AdustColumnOffset - C/AL Locals window, on the Variables tab, add a variable. In the Name field, enter OldColunnOffset. In the DataType field, select Integer.

    9. In the C/AL Globals window, on the Function tab, on a new line, enter UpdateColumnCaptions, and then click Locals.

    10. In the UpdateColumnCaptions - C/AL Locals window, on the Variables tab, enter a new variable. In the Name field, enter ColumnNo. In the DataType field, select Integer.

    11. In the UpdateColumnCaptions - C/AL Locals window, on the Variables tab, enter a new variable. In the Name field, enter i. In the DataType field, select Integer.

    12. In the C/AL Globals window, on the Variables tab, add a new variable. In the Name field, enter ColumnOffset. In the DataType field, select Integer.

    13. In the C/AL Editor, enter the following code in the AdjustColumnOffset function.

      CopyCode image Copy Code
      OldColumnOffset := ColumnOffset;
ColumnOffset := ColumnOffset + Delta;
IF ColumnOffset + 12 > TempColumnLayout.COUNT THEN
  ColumnOffset := TempColumnLayout.COUNT - 12;
IF ColumnOffset < 0 THEN
  ColumnOffset := 0;
IF ColumnOffset <> OldColumnOffset THEN BEGIN
  UpdateColumnCaptions;
  CurrForm.UPDATE(FALSE);
  CurrForm.UPDATECONTROLS;
END;

    14. In the C/AL Editor, enter the following code in the UpdateColunnCaptions function.

      CopyCode image Copy Code
      CLEAR(ColumnCaptions);
IF TempColumnLayout.FINDSET THEN
  REPEAT
    ColumnNo := ColumnNo + 1;
    IF (ColumnNo > ColumnOffset) AND (ColumnNo - ColumnOffset <= ARRAYLEN(ColumnCaptions)) THEN
      ColumnCaptions[ColumnNo - ColumnOffset] := TempColumnLayout."Column Header";
  UNTIL (ColumnNo - ColumnOffset = ARRAYLEN(ColumnCaptions)) OR (TempColumnLayout.NEXT = 0);
// Set unused columns to blank to prevent RTC to display control ID as caption
FOR i := ColumnNo - ColumnOffset + 1 TO ARRAYLEN(ColumnCaptions) DO
  ColumnCaptions[i] := ' ';
      Note Note

      Even though you replace the original code on these command button controls, we recommend that you copy them from a redesigned form, such as form 9202, and then replace the code so that the captions are identical. That way, you do not need to change the transformation input to promote the actions on the page.

  11. On the File menu, click Save. Confirm that the Compile check box is selected, and then click OK.

Expand image Next Steps

Viktor's redesigned Acc. Schedule Overview form has the same functionality as the original form but does not use a matrix box control. Now Viktor can transform his redesigned form to a page. To transform the form he must:

  • Install the form transformation tool. For more information, see How to: Install the Form Transformation Tool.

  • Prepare the form transformation tool input. For more information, see Preparing Transformation Tool Input.

  • Transform the form. For more information, see Transforming Forms.

Expand image See Also

Tasks

How to: Redesign Matrix Forms
How to: Arrange Page Fields in Rows and Columns Using a FixedLayout Control

Concepts

Transforming Forms to Pages


Preparing Transformation Tool Input

Preparing Transformation Tool Input

The transformation input files are XML files that define mapping rules. For most forms, before you transform forms to pages that you can use with the RoleTailored client, you must define the transformation input. Some simple forms do not require input, but for most forms, we recommend that you use the Transformation Input File (TIF) Editor to specify form transformation input files. You can also modify the transformation input .xml files directly instead of using the TIF Editor.

This topic describes the TIF Editor and the workflow that you use to create and modify transformation input files by using the TIF Editor.

For more information about transformation input files, see Understanding Form Transformation Input Files.

Elements of the Transformation Input File Editor

The user interface for the TIF Editor is a form that you run from Object Designer in the Classic client. The form that you run is form 177000, Transformation Forms. In this way, the TIF Editor offers a familiar environment for creating and modifying the transformation input in a tabular format rather than in the XML file. If you use the Microsoft Dynamics NAV Developers Toolkit, the TIF Editor also has data about form objects, which significantly improves efficiency and accuracy of the input data entry.

The TIF Editor consists of the following objects:

  • TIF.fob – A set of objects that make up the editor’s functionality.

  • FormToPageTypeMapping.txt - A list of form types, definitions, and their matching page types.

  • Schemas - TransformationInput.xsd, DeletePageElement.xsd, IgnorePage.xsd, IgnorePage.xsd, and MovePageElement.xsd

Transformation Input File Editor Workflow

In your application, you may have forms that are the standard application forms, with or without customizations, and you may have Microsoft Certified Partner solution forms. The following steps summarize the workflow for the TIF Editor. Some steps in the workflow are optional, based on whether you have standard application forms or partner solution forms.

  1. Install the TIF Editor. For more information, see How to: Install the Transformation Input File Editor.

  2. If you have standard application forms, import the standard application transformation input files to view and modify transformation input specifications. For more information, see How to: Import Transformation Input Files.

  3. If you have partner solution forms, populate the TIF Editor with these forms. For more information, see How to: Get Forms in the Transformation Input File Editor.

  4. Import the list of form types, definitions, and their matching page types, to be used for lookup. For more information, see How to: Import Form to Page Mappings.

  5. Specify the page type for partner solution forms. The standard application forms already have the page type specified. For more information, see How to: Specify PageType.

  6. Specify the CardFormID for list forms that have associated cards and that are partner solution forms. The standard application forms already have the CardFormID specified. For more information, see How to: Specify CardFormID.

  7. Define additional input specifications for the form transformation. For more information, see Specifying Form Transformation Rules with the Transformation Input Files Editor.

  8. Validate form transformation. For more information, see How to: Validate Form Transformation.

  9. Export the input data out of the TIF Editor to create XML input files. The files are validated against the XML schemas. For more information, see How to: Export Files from the Transformation Input File Editor.


Understanding Form Transformation Input Files

Understanding Form Transformation Input Files

The form transformation tool uses several input files. To transform forms to pages, you must define a set of mapping rules, which are contained in five transformation input files. The rules map objects in the Classic client to objects in the RoleTailored client.

When you install the form transformation tool, you get the transformation input files for the standard application. You can modify these input files to account for changes that you have made in customized forms. Additionally, you can create new transformation input files for your own forms. We recommend that you use the Transformation Input File (TIF) Editor to modify the standard application transformation input files or to create new transformation input files. You can also modify the .xml files directly.

This topic includes the following:

  • Descriptions of each of the transformation input files.

    • Details about how the TIF Editor displays the information in the .xml files. Using the TIF Editor is the recommended method of modifying the input files.

    • Details and snippets of the .xml files, which will be valuable if you choose to modify the input files directly instead of using the TIF Editor.

  • Details about how to use the functions in the TIF Editor to modify the transformation input files.

  • Other files that the transformation tool uses.

Transformation Input Files

The transformation input files that define form to page mappings are the following:

  • TransformPages.xml

  • IgnorePages.xml

  • MovePages.xml

  • DeleteElements.xml

  • MoveElements.xml

To edit these files by using the TIF Editor, you use several different functions. For more information about the functions, see TIF Editor Functions in this topic.

TransformPages.xml

The TransformPages.xml file contains the two required page properties:

  • Page Type

  • Card Form ID

In addition, this file defines additional instructions for user experience (UX) transformation. For more information about UX Transformation, see Form Transformation Objectives.

TransformPages.xml in the TIF Editor

After you import the TransformPages.xml file into the TIF Editor, each form that is listed in the file is added to the editor, with the form type, page type, and card form ID properties. Any additional transformation information is also added to the editor, such as promoted actions, added FactBoxes, and HomeParts.

TransformPages XML File

In the TransformPages.xml file, each page is assigned a PageType. List pages that have an associated card have a CardFormID. For example, the section of the TransformPages.xml file for Page 16, Chart of Accounts includes the following.

CopyCode image Copy Code
<Page ID="16" Name="Chart of Accounts">
   <Transformation FormType="Chart of Accounts" />
-  <Properties>
     <PageType>List</PageType>
     <CardFormID>17</CardFormID>

The TransformPages.xml file also contains information about controls and elements on the page. For example, Page 16, Chart of Accounts includes a FactBox with account dimensions. The FactBox is page 9083, Dimensions FactBox. The FactBox control will be assigned the control ID 300000001 on the transformed page instead of being automatically assigned an ID by the transformation tool. The Visible property on the FactBox by default is set to No.

CopyCode image Copy Code
-  <Controls>
-    <FactBoxArea>
-       <Part>
-         <Properties>
             <NewID>300000001</NewID>
             <Visible>No</Visible>
             <PartType>Page</PartType>
             <PagePartID>9083</PagePartID>
             <SubFormLink>Table ID=CONST(15),No.=FIELD(No.)</SubFormLink>

Finally, the TransformPages.xml file contains specifications for new actions, the location of the actions in the menu, and specifications for both new and existing actions that have been promoted. For example, Page 16, Chart of Accounts, includes an action for the existing command Indent Chart of Accounts (MenuItem ID = 30). The .xml file specifies that this action be promoted to the Action Pane. It also includes a new action to open page 116, G/L Registers. This action is also promoted to the Action Pane. The action will be assigned the control ID 300000002 on the transformed page instead of being automatically assigned an ID by the transformation tool.

CopyCode image Copy Code
- <ActionItems>
-    <Action>
       <ID>30</ID>
       <Promoted>Yes</Promoted>
       <PromotedCategory>Process</PromotedCategory>
     </Action>
 </ActionItems>
  <RelatedInformation>
-   <Action>
      <NewID>300000002</NewID>
      <CaptionML>ENU=G/L Register</CaptionML>
      <RunObject>Page 116</RunObject>
      <Promoted>Yes</Promoted>
      <PromotedCategory>Process</PromotedCategory>
    </Action>
 </RelatedInformation>

IgnorePages.xml

The IgnorePages.xml file lists forms that the transformation tool will ignore. The tool will not create pages for the forms listed in this file. This is relevant in the following situations:

  • If a form cannot be transformed to a page for technical reasons, for example, forms with matrix box controls.

  • If you choose not to transform a form to a page.

IgnorePages.xml in the TIF Editor

After you import the IgnorePages.xml file into the TIF Editor, the Ignore column is populated with a check mark for each form in the IgnorePages.xml file. For example, after you import the IgnorePages.xml file for the standard application into the editor, the line for form 113, Budget, has a check mark in the Ignore column.

IgnorePages XML File

The IgnorePages.xml file lists each of the pages to ignore. For example, pages 113, 408, and 490 are included in the following section of the file.

CopyCode image Copy Code
  <Page ID="113" Name="Budget" />
  <Page ID="408" Name="G/L Balance by Dimension" />
  <Page ID="490" Name="Acc. Schedule Overview" />

MovePages.xml

The MovePages.xml file allows you to specify rules for replacing one form with another. For example, if you redesign a form because it cannot be converted to a page by creating a new form, the new form replaces the original form. The MovePages.xml file contains the IDs of both the original form that will be replaced and the new form that replaces the original. You must also include the original form in the IgnorePages.xml file.

MovePages.xml in the TIF Editor

After you import the MovePages.xml file into the TIF Editor, the DestinationID, DestinationName, and FormReplacedBy columns are populated with information from the file. A form that is being replaced has the form ID of the new form in the FormReplacedBy column. A new form that replaces another form has the ID and name of the original form in the DestinationID and DestinationName columns. For example, after you import the MovePages.xml file for the standard application into the editor, the line for form 113, Budget, has ID 9202 in the FormReplacedBy column, indicating that form 113 will be replaced by the new form, 9202. The line for form 9202 has ID 113 in the DestinationID column and "Budget" in the DestinationName column, indicating that form 9202 replaces form 113, Budget.

Note Note

The original form still exists and retains its original ID. The transformed page has the ID of the original form.

MovePages XML File

The MovePages.xml file lists each of the replaced forms. For example, in the standard application MovePages.xml file, the following line instructs the form transformation tool to replace the original form 113, Budget, with the new form 9202, the new, redesigned Budget form. The original form 113, Budget, is not transformed.

CopyCode image Copy Code
  <Page ID="9202" Name="_Budget" destinationID="113" destinationName="Budget" />

DeleteElements.xml

The DeleteElements.xml file lists control IDs for a given form that you do not want to transform. It allows you to specify individual controls on selected forms that cannot or should not be transformed onto the corresponding page. An InfoPane frame on a sales document is an example of a layout that cannot be automatically converted to a corresponding control or element in the RoleTailored client. Instead, you should add a FactBox. Another example is the ”Post Code/City” label. The DeleteElements.xml file for the standard application specifies that this label is deleted from all the forms where this control is found. The reason it is deleted is that in its caption, the label refers to two fields.

DeleteElements.xml in the TIF Editor

After you import the DeleteElements.xml file, the Delete Page Elements window for each form in the file is populated with elements that will not be transformed. For example, after you import the DeleteElements.xml file for the standard application, in the TIF Editor, select form 42, Sales Order, click Input, and then click Delete Page Control. The Delete Page Elements window lists four controls that will not be transformed: 205, 87, 96, and 98. The following table describes these controls.

Control ID | Description
205 | The InfoPane frame
87 | The Post Code/City label on the General tab
96 | The Post Code/City label on the Invoicing tab
98 | The Post Code/City label on the Shipping tab
Note Note

If you delete a ControlContainer, such as Tab or Frame, you will also delete all other controls that have this container as a parent. Therefore, you do not need to specify deletion rules for each control on a tab or frame that you delete.

DeleteElements XML File

The DeleteElements.xml file lists each of the controls that will be deleted for each page. For example, in the DeleteElements.xml file for the standard application, for form 42, Sales Order, the InfoPane frame and three Post Code/City labels are deleted from the page.

CopyCode image Copy Code
- <Page ID="42" Name="Sales Order">
  <Element ID="205" />
  <Element ID="87" />
  <Element ID="96" />
  <Element ID="98" />

MoveElements.xml

The MoveElements.xml file lists properties for form elements that specify UX modifications. The following table shows the properties that you can use in the MoveElements.xml file.

Property | Description
FixedLayout ID | Specifies each label control in the first row of a page with a matrix-like layout.
PromotedField | Specifies properties that are essential and will be displayed as a summary on the collapsed FastTab.
InstructionalTextML | Specifies label controls that contain text instructions, such as those found on confirmation dialog boxes.
Add image to action by caption | Assigns an icon to an action that is shown next to the action when the action is promoted onto the Action Pane. This assignment is based on mapping the icon and action caption.
Promote action by caption | Identifies by caption a few recurrent actions, such as Post, Print, and Register that are promoted to the action pane. You apply this property to the actions instead of specifying them on each form.
Add big image by caption | Identifies by caption a few recurrent actions, such as Post, Print, and Register that are assigned a big icon. You apply this property to the actions instead of specifying them on each form.
Add shortcut to action by caption | Assigns a shortcut to a new action.
Move shortcuts | Replaces shortcuts used in the Classic client.
Move action by caption | Specifies the menu in the menu bar to which actions from a menu button will be moved.
Move trendscape control by caption | Specifies that the period options for a trendscape form will be moved to a drop-down list.
TabControlNewIDs | Specifies a control ID that is assigned to a tab in a TabControl. Tabs in a TabControl are transformed to FastTabs on a page. If you do not specify a control ID for tabs, then an ID is automatically assigned.
AdditionalField | Specifies a field that is hidden from the expanded FastTab by default. To view the hidden fields, click Show more fields in the FastTab.

MoveElements.xml in the TIF Editor

After you import the MoveElements.xml file into the TIF Editor and then click Input, the various options that you can select will display the elements that will be moved. The following table shows TIF Editor examples of each of the properties and elements in the MoveElements.xml file for the standard application.

Property TIF Editor example for the standard application

FixedLayout ID

After you import the MoveElements.xml file into the TIF Editor, select form 151, Customer Statistics, click Input, click Add, and then click New Control Property. The Move Page Elements window lists four controls that are the labels on the first row of the matrix. These controls are the following:

  • 121 "This Period" label on the Sales tab

  • 21 "This Year" label on the Sales tab

  • 22 Last Year" label on the Sales tab

  • 23 To Date" label on the Sales tab

For more information about the FixedLayout property, see How to: Set the FixedLayout Property.

PromotedField

After you import the MoveElements.xml file into the TIF Editor, select form 21, Customer Card, click Input, click Add, and then click New Control Property. The Move Page Elements window lists several controls that have the Group field set to PromotedField. These controls will be displayed as a summary if you collapse the FastTab on the transformed Customer page.

AdditionalField

After you import the MoveElements.xml file into the TIF Editor, select form 21, Customer Card, click Input, click Add, and then click New Control Property. In the Move Page Elements window, for any of the controls listed, in the Group field, select AdditionalField from the drop-down list. This control will be hidden from the expanded FastTab. To view the hidden field, click Show more fields in the FastTab.

InstructionalTextML

After you import the MoveElements.xml file into the TIF Editor, select form 6002, Cancelled Allocation Reasons, click Input, click Add, and then click New Control Property. The Move Page Elements window lists control ID 2 as InstructionTextML. The control with ID 2 is the label on the form with the caption, "Do you want to cancel the allocation?"

Add image to action by caption

After you import the MoveElements.xml file into the TIF Editor, click Input, click Add by Caption, and then select Image to Action. The Add Image by Caption window lists values for the CaptionML property. Every action with the CaptionML property that matches a value in the list will have an icon displayed with the action. The name of the icon is listed in the NewName column.

Promote action by caption

After you import the MoveElements.xml file into the TIF Editor, click Input, and then click Promote Action by Caption to view the actions that are promoted to the action pane. The Promote Action by Caption window lists values for the CaptionML property. Every action with the CaptionML property that matches a value in the list will be promoted to the Action Pane.

Add big image by caption

After you import the MoveElements.xml file into the TIF Editor, click Input, click Add by Caption, and then click Big Image to Action. The Add Big Image by Caption window lists values for the CaptionML property. Every action with the CaptionML property that matches a value in the list will have a big icon displayed with the action.

Add shortcut to action by caption

After you import the MoveElements.xml file into the TIF Editor, click Input, click Add by Caption, and then select Shortcut to Action. The Add ShortCut by Caption window shows the CaptionML property of new commands and the shortcut that will be assigned to them in the RoleTailored client.

Move shortcuts

After you import the MoveElements.xml file into the TIF Editor, click Input, click Move, and then click Shortcuts. The Shortcuts - Move Elements window shows the shortcuts that will be replaced in the RoleTailored client.

If a new shortcut is not defined, then the existing shortcut will be deleted.

Move action by caption

After you import the MoveElements.xml file into the TIF Editor, click Input, click Move, and then click Action by Caption. The Move Action by Caption window shows the menu in the menu bar to which an action from a menu button will be moved. All actions whose CaptionML property matches a value in the list will be moved to the menu listed in the destinationType column.

By default, when forms are transformed, actions are moved to the Related Information menu. Specifying actions in the Move Action by Caption window overrides the defaults.

Move trendscape control by caption

After you import the MoveElements.xml file into the TIF Editor, click Input, click Move, and then click Trendscape Control by Caption. The Move Trendscape Control window shows period options for trendscape forms. The period options specified by OptionCaptionML will be moved to a drop-down list. The caption specified by CaptionML will be the label for the list.

TabCtrlNewIDs

After you import the MoveElements.xml file into the TIF Editor, click Input, click Add, and then click New IDs in TabControl. The New ID in TabControl window allows you to specify TabControl IDs and PageNamesML values for the form and the new control ID for the FastTab on the transformed page.

In the TIF Editor, click Input, click Add, and then click New Control Property. If you specified TabControl IDs in the New ID in TabControl window, then the Move Page Elements window lists the TabControl ID.

MoveElements XML File

The MoveElements.xml file lists each of the controls on a page that will be assigned a new property or moved. The following table shows .xml examples of each of the properties in the MoveElements.xml file for the standard application.

Note Note

You cannot update the CaptionML property or the OptionCaptionML property of an element by using the MoveElements.xml file. The CaptionML and OptionCaptionML in the MoveElements.xml file is used by the transformation tool only for searching. For more information about translating multilanguage strings, see How to: Add Translated Strings By Importing and Exporting Multilanguage Files. For more information about preserving translations during form transformation, see How to: Create the PageTranslations.txt File.

Property XML example for the standard application

FixedLayout ID

The following lines specify four labels on form 151, Customer Statistics that are marked with the FixedLayout ID property.

CopyCode image Copy Code
<Page ID="151" Name="Customer Statistics">
  <FixedLayout ID="121" />
  <FixedLayout ID="21" />
  <FixedLayout ID="22" />
  <FixedLayout ID="23" />

PromotedField

The following lines specify a set of fields on form 21, Customer Card that are marked with the PromotedField property.

CopyCode image Copy Code
<Page ID="21" Name="Customer Card">
  <PromotedField ID="2" Name=""No."" />
  <PromotedField ID="4" Name="Name" />
  <PromotedField ID="16" Name="Contact" />

AdditionalField

The following line specifies that control 16, the Contact field, on form 21, Customer Card, is hidden from the expanded FastTab.

CopyCode image Copy Code
<Page ID="21" Name="Customer Card">
  <AdditionalField ID="16" Name="Contact"/>

InstructionalTextML

The following lines specify that control ID 2 on page 6002, Cancelled Allocation Reasons, will be marked as InstructionTextML.

CopyCode image Copy Code
<Page ID="6002" Name="Cancelled Allocation Reasons">
  <InstructionalTextML ID="2" Name=""/>

Add image to action by caption

The following line instructs the tool to set an image called “Invoice” to every action in the application whose CaptionML property is “Sales Invoice."

The page ID in this line, -5, specifies the group of Add Image to Action by Caption lines in the file. It does not specify a particular page.

CopyCode image Copy Code
<Page ID”-5” Name="Add Image to Action by Caption" NewName="Invoice" CaptionML="ENU=Sales Invoice" />

Promote action by caption

The following line instructs the tool to promote all actions whose CaptionML property is "ENU=Post" to the Action Pane.

The page ID in this line, -2, specifies the group of Promote Action lines in the file. It does not specify a particular page.

CopyCode image Copy Code
<Page ID"-2" Name="Promote Action" CaptionML="ENU=Post" />

Add PromoteIsBig by Caption

The following line instructs the tool to add a big image to all actions whose CaptionML property is "ENU=Post."

The page ID in this line, -6, specifies the group of Add PromoteIsBig by Caption lines in the file. It does not specify a particular page.

CopyCode image Copy Code
<Page ID="-6" Name="Add PromoteIsBig by Caption" CaptionML="ENU=Post" />

Add shortcut to action by caption

The following line instructs the tool to add a shortcut to all actions whose CaptionML property is "ENU=Edit Journal." The shortcut key is Return.

The page ID in this line, -4, specifies the group of Add Short Cut to Action by Caption lines in the file. It does not specify a particular page.

CopyCode image Copy Code
<Page ID="-4" Name="Add Short Cut to Action by Caption" NewName="Return" CaptionML="ENU=Edit Journal"/>

Move shortcut

The following line instructs the tool to replace a shortcut in the Classic client with a new shortcut in the RoleTailored client.

The page ID in this line, -1, specifies the group of Add Short Cut to Action by Caption lines in the file. It does not specify a particular page.

CopyCode image Copy Code
<Page ID="-1" Name="F5" NewName="Ctrl+Shift+L"/>

Move action by caption

The following line instructs the tool to move all actions whose CaptionML property is "ENU=Print" to the Actions menu. By default, when forms are transformed, actions are moved to the Related Information menu. This line overrides the default setting.

The page ID in this line, -3, specifies the group of Place in ActionContainer lines in the file. It does not specify a particular page.

CopyCode image Copy Code
<Page ID="-3" Name="Place in ActionContainer" CaptionML="ENU=Print" destinationType="ActionItems"/>

Controls on trendscape forms

The following line instructs the tool to move period options on trendscape forms to a drop-down list with the caption View by.

The page ID in this line, -7, specifies the group of lines in the file for controls on trendscape forms. It does not specify a particular page.

CopyCode image Copy Code
<Page ID="-7" Name="Controls on trendscape forms will be moved to the top tab" OptionCaptionML="ENU=Day,Week,Month,Quarter,Year" CaptionML="ENU=View by"/>

TabControlNewIDs

The following line instructs the tool to assign the ID 3000000 to the FastTab control that is transformed from the Invoicing tab on the form.

CopyCode image Copy Code
<TabControlNewIDs ID="1" PageNameML="ENU=Invoicing" NewID="3000000"/>

TIF Editor Functions

The TIF Editor includes several functions that allow you to modify the transformation input files. The following table shows the functions on the Input menu in the TIF Editor, the transformation input file that each function modifies, and comments about each function.

Menu Submenu Transformation input file Comments

Add

New and Promoted Actions

TransformPages.xml

Use to add actions to the menu bar and to the Action Pane, and to specify big images for promoted actions.

Add

FactBoxes

TransformPages.xml

Use to add FactBoxes to the FactBox pane.

Add

HomeParts

TransformPages.xml

Use to add Home Part elements to a Role Center.

Add

New Control Property

MoveElements.xml

Use to add the following to a control:

  • FixedLayout property

  • PromotedField property

  • InstructionalTextML property

  • TabCtrlNewIDs property

  • AdditionalField property

Add

New IDs in TabControl

MoveElements.xml

Use to assign a specific control ID to a new FastTab control.

Add by Caption

Image to Action

MoveElements.xml

Use to add an image to an action. The image files are part of the source code and cannot be modified. Every action with a given CaptionML value will have the same image.

Add by Caption

Big Image to Action

MoveElements.xml

Use to add a big image to an action. The image files are part of the source code and cannot be changed. Every action with a given CaptionML value will have a big image.

Add by Caption

Shortcut to Action

MoveElements.xml

Use to add a shortcut to an action.

Move

Action by Caption

MoveElements.xml

Use to move an action in the menu bar to a different menu. By default, when forms are transformed, actions are moved to the Related Information menu.

Move

Shortcuts

MoveElements.xml

Use to replace a shortcut that is used in the Classic client with a new shortcut in the RoleTailored client.

Move

Trendscape Control by Caption

MoveElements.xml

Use to specify period options on trendscape forms.

Promote Action by Caption

MoveElements.xml

Use to promote to the Action Pane all actions with a given caption.

DeletePageControl

DeleteElement.xml

Use to specify individual controls on forms that will not be transformed onto the corresponding page.

Bulk Edit Actions

MoveElements.xml

Use to view and specify actions in menus for all pages.

Other Form Transformation Files

The other files that the transformation tool uses are the following:

  • Coderules.txt Code rules that are used to remove unsupported triggers and methods. For more information, see Code Rules.

  • Forms.xml The file to which you export the existing forms that you want to transform.

  • Schema files Files that define the structure of the input and output files of the form transformation tool.

    • ApplicationObjects.xsd

    • Common.xsd

    • DeletePageElement.xsd

    • Form.xsd

    • IgnorePage.xsd

    • MovePage.xsd

    • MovePageElement.xsd

    • Page.xsd

    • Report.xsd

    • TransformationInput.xsd

  • PageTranslations.txt Control IDs associated with translation strings for multilanguage applications. You create this file by running the Translate Export function in the Tools menu.

See Also

Concepts

Form Transformation Tool Overview


How to: Install the Transformation Input File Editor

How to: Install the Transformation Input File Editor

To edit transformation input files, we recommend that you install the Transformation Input File (TIF) Editor. To install the TIF Editor, you import the TIF.fob file. You can also install the Microsoft Dynamics NAV Developers Toolkit, if you want lookup assistance for selecting IDs in the TIF Editor.

Before you begin this procedure, confirm that you have installed the form transformation tool. For more information, see How to: Install the Form Transformation Tool.

To install the TIF Editor

  1. In the Classic client, click Tools, and then click Object Designer.

  2. In the File menu, select Import.

  3. In the Import Objects window, select the TIF.fob file, and then click Open.

    Note Note

    The TIF.fob file is located in the TIF Editor folder, which was created when you installed the form transformation tool.

  4. In the dialog window, click Yes to import all objects.

  5. (optional) Install the Microsoft Dynamics NAV Developers Toolkit. You can find the toolkit on PartnerSource.

See Also

Concepts

Understanding Form Transformation Input Files


How to: Import Transformation Input Files

How to: Import Transformation Input Files

Many of the mapping rules that you will use to transform forms are defined in the transformation input .xml files. You can import the .xml files that contain the mapping rules into the Transformation Input File (TIF) Editor and then modify the mapping rules. The transformation input files are the following:

  • TransformPages.xml

  • IgnorePages.xml

  • MovePages.xml

  • DeleteElements.xml

  • MoveElements.xml

When you install the form transformation tool, you get the transformation input files for the standard application. If the forms in your application are based on the standard application forms, use the following procedures to import the transformation input .xml files for the standard application forms into the TIF Editor, and to view and modify the standard application transformation input specifications by using the TIF Editor.

If the forms in your application are Microsoft Certified Partner solution forms and if you have previously created your own transformation input files, you can also use the following procedures to import your own transformation input .xml files into the TIF Editor and to modify the rules in these files by using the TIF Editor.

Before you begin these procedures, you must do the following:

  • Install the TIF Editor. For more information, see How to: Install the Transformation Input File Editor.

  • If you are importing your own transformation input files and not the standard application input files, ensure that you have created the transformation input files. For more information, see Preparing Transformation Tool Input.

To import transformation input files

  1. In Object Designer, click Form, select form 177000, Transformation Forms, and then click Run.

  2. In the Transformation Forms window, click Setup, and then click Transformation Setup Card.

  3. In the Transformation Setup window, under TIF path Import, specify the path where the transformation input files are located.

  4. Close the Transformation Setup window to save your changes.

  5. In the Transformation Forms window, click Setup, and then click Import All Transformation Input.

    Note Note

    To import the transformation input files one at a time, click Setup, click Import Transformation Input, and then select one of the transformation input files.

To modify the transformation input files

  • In the Transformation Forms window, you can make changes to any of the fields that you want to change. For more information about making modifications, see the following topics:

    • Understanding Form Transformation Input Files

    • Specifying Form Transformation Rules with the Transformation Input Files Editor

    Note Important

    For each form in the TIF Editor, at a minimum, you must specify the PageType property. If the form is a list type and has a card form associated with it, you must also specify the CardFormID property. Confirm that you have specified these required properties.

See Also

Tasks

How to: Specify PageType
How to: Specify CardFormID


How to: Get Forms in the Transformation Input File Editor

How to: Get Forms in the Transformation Input File Editor

The following procedure describes how to populate the Transformation Input File (TIF) Editor with the forms for which you want to create transformation input by using the Get Forms function. You can also add forms to the TIF Editor manually by entering the form ID.

Use the Get Forms command to get Microsoft Certified Partner solution forms. If you have forms that are based on the standard application forms, you will get those forms into the TIF Editor when you import the standard application transformation input files.

Before you begin this procedure, confirm that you have installed the TIF Editor. For more information, see How to: Install the Transformation Input File Editor.

To populate the TIF Editor with forms

  1. In Object Designer, click Form, select form 177000, Transformation Forms, and then click Run.

  2. In the Transformation Forms window, click Setup, and then select Get Forms to get forms into the TIF Editor.

  3. In the Get Forms window, to get all forms in your application, click OK. To get one or more specific forms, use the Filter fields, and then click OK.

  4. Verify that the Transformation Forms window displays the ID and Name of the forms that you specified.


How to: Import Form to Page Mappings

How to: Import Form to Page Mappings

Each page has a type. You must specify the page type before you can transform a form to a page. To simplify the task of specifying page types, forms have also been assigned types and a form type to page type mapping has been created. Therefore, to specify a page type, you can choose to first specify the form type. Then, if you import the form to page mappings, the page type will be specified automatically.

For example, in the standard application, form 5, Currencies, is defined as a List type form, which is mapped to a List type page. Similarly, form 39, General Journal, is defined as a Journal type form, and form 7023, Sales Price Worksheet, is defined as a Worksheet type form. Both map to Worksheet type pages.

To use the lookup capability for page types in the Transformation Input File (TIF) Editor, you must import the FormToPageTypeMapping.txt file. The following procedure describes how to import the FormToPageTypeMapping.txt file.

Before you begin this procedure, you must do the following:

  • Install the TIF Editor. For more information, see How to: Install the Transformation Input File Editor.

To import the default form type to page type mapping

  1. In the Transformation Forms window, click Setup, and then select Import FT-PT Mapping.

  2. In the Import/Export Form Types window, in the File Name field, click the ellipsis button (...).

  3. In the Dataport Import File Name window, browse to the FormToPageTypeMapping.txt file, and then click Open.

    Note Note

    The FormToPageTypeMapping.txt file is located in the TIF Editor folder, which was created when you installed the form transformation tool.

  4. In the Import/Export Form Types window, under Direction, select Import, and then click OK.

  5. Verify that the form types, with their definitions and matching page types, are now available for lookup and selection from the FormType field in the Transformation Forms window.

See Also

Concepts

Form Type to Page Type Mapping


How to: Specify PageType

How to: Specify PageType

Each page has a type. You must specify the page type before you can transform a form to a page. To simplify the task of specifying page types, forms have also been assigned types and a form type to page type mapping has been created. Therefore, to specify a page type, you can choose to first specify the form type. Then, if you import the form to page mappings, the page type will be specified automatically.

You can specify the page type by using the Transformation Input Files (TIF) Editor or by modifying the form transformation input .xml files directly. The following procedure describes how to specify the page type by using the TIF Editor. For more information about modifying the transformation input .xml files directly, see Understanding Form Transformation Input Files.

Before you begin this procedure, you must do the following:

  • Install the TIF Editor. For more information, see How to: Install the Transformation Input File Editor.

  • Populate the TIF Editor with the forms that you want to transform to pages. For more information, see How to: Get Forms in the Transformation Input File Editor.

  • Import the list of form types, definitions, and their matching page types that you will use for lookup. For more information, see How to: Import Form to Page Mappings.

To specify the page type

  1. In the Transformation Forms window, in the FormType column, click the lookup button.

  2. In the Form Types window, select the row with the form type for the selected form, and then click OK.

  3. (optional) To view the page type associated with the form type that you selected, in the Transformation Forms window, click the PageType field.

See Also

Concepts

Form Type to Page Type Mapping


How to: Specify CardFormID

How to: Specify CardFormID

To support the navigation principle in the RoleTailored client that a user must always be able to move from a list place to a card, all list forms that you want to transform and that have cards associated with them must have a CardFormID property specified. The CardFormID specifies the card form with which the list form is associated. The following procedure describes how to specify the CardFormID.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For more information, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor. For more information, see How to: Get Forms in the Transformation Input File Editor.

  • Import the list of form types that you will use for lookup. For more information, see How to: Import Form to Page Mappings.

  • Specify the page type for the forms in the TIF Editor. For more information, see How to: Specify PageType.

To specify the CardFormID

  • In the Transformation Forms window, for each form whose FormType is List, select the form ID in the CardFormID field of the card that is associated with the list form.

    Note Note

    If you use the Microsoft Dynamics NAV Developers Toolkit with the TIF Editor, you can use the lookup function from the CardFormID field in the Transformation Forms window. The lookup function displays the card form that is associated with the same source table as the list form on the line that is selected. You can find the Microsoft Dynamics NAV Developers Toolkit on PartnerSource.


Specifying Form Transformation Rules with the Transformation Input Files Editor

Specifying Form Transformation Rules with the Transformation Input Files Editor
See Also

This section explains how you can use the Transformation Input File (TIF) Editor to specify additional input for transformation. Some topics in this section relate to tailoring the user interface in transformed pages. Other topics relate to modifying the input so that the transformed page has the same layout as the original form.

If you are transforming a lot of forms you may want to plan your mappings before entering anything directly into the TIF Editor.

See Also

Tasks

How to: Add Actions to a Page By Using Transformation Input
How to: Add FactBoxes to Pages By Using Transformation Input
How to: Add Home Parts to a Role Center By Using Transformation Input
How to: Add Images to the Action Pane by Using Transformation Input
How to: Add Shortcuts to New Commands
How to: Change the Menu Where an Action Resides
How to: Exclude Specific Controls from Transformation
How to: Mark Labels on Dialogs as Instructions
How to: Modify Shortcut Keys
How to: Promote Actions to the Action Pane By Using Transformation Input
How to: Promote a Field to the FastTab Header By Using Transformation Input
How to: Set the FixedLayout Property


How to: Add Actions to a Page By Using Transformation Input

How to: Add Actions to a Page By Using Transformation Input

Actions are menu items that appear on pages and are grouped under the following three menus:

  • Actions

  • Related Information

  • Reports

In the RoleTailored client, View, Edit, New and Delete are default actions that appear on every page.

You can add additional actions to pages by using Page Designer or by creating additional input when you transform your forms. For example, the Customer List page has the following additional actions:

  • Cash Receipt Journal (on the Actions menu).

  • Prices (on the Related Information menu, point to the Sales submenu).

  • Customer Top 10 List (on the Reports menu).

This topic describes how to add an action to a page during form transformation. The following illustration shows the Page Actions window that is part of the TIF Editor, with examples of actions and reports added to form 21, Customer Card.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

Adding Actions

To add an action to a page by using the TIF Editor

  1. In the Transformation Forms window, select a form to which you want to add an action or report, click Input, point to Add, and then click New and Promoted Actions.

  2. In the Page Actions window, in the RunObjectID field of a new line, enter the ID of the page or report that you want to add to the transformed page.

  3. In the RunObjectType field, select the object type that you want to add, such as a page or report.

  4. In the ActionsType field, select the container on the menu bar in which you want your action to appear. The following table shows the options that you can choose.

    Option Description

    NewDocumentItems

    Action will appear in the Action menu under the New Document submenu. If action is also promoted, it will appear in the New section of the Action Pane.

    ActionItems

    Action will appear in the Actions menu. If action is also promoted, it will appear in the Process section of the Action Pane.

    RelatedInformation

    Action will appear in the Related Information menu. If action is also promoted, it will appear in the Process section of the Action Pane.

    Report

    Action will appear in the Reports menu. If action is also promoted, it will appear in the Reports section of the Action Pane.

    ActivityButtons

    Action will appear on a Role Center page.

  5. In the RunFormMode field, specify the mode in which you want your action to open the page. If you select Create, you will create a new item when you click the action, such as a new Sales Order. If you select View, you will be able to view the page or report when you click the action, but you will not be able to edit the data. If you select Edit, you will be able to edit the information on the page when you click the action. If you do not specify the mode, the default mode Edit is used.

  6. In the CaptionML field, specify the CaptionML property for the action. The CaptionML property is in the format, ENU=<caption>.

  7. (optional) In the RunFormLink field, specify the relationship for linking a field in the page to a field the in the page that the action will run. For example, if from the Customer list you want to create a new sales order for a specific customer and you want the customer number pre-filled when you create the sales order, then you must enter Sell-to Customer No.=FILED(No.) in the RunFormLink field.

  8. (optional) In the NewID field, enter the ID that you want the transformation tool to assign to the action on the page. If you do not enter a value, then the tool assigns an ID automatically. For more information, see Transforming Control and Menu IDs.

  9. Close the Page Actions window to save your changes.

See Also

Tasks

How to: Promote Actions to the Action Pane By Using Transformation Input
How to: Add Images to the Action Pane by Using Transformation Input
How to: Add Actions to a Page

Concepts

Developing Multilanguage-Enabled Applications


How to: Add FactBoxes to Pages By Using Transformation Input

How to: Add FactBoxes to Pages By Using Transformation Input

FactBoxes are containers for displaying additional data on a page. For example, on the Customer List page a user may want to see additional information about sales history of a specific customer on the same page. You can add a FactBox to the page that links to the Sales History page.

You can add FactBoxes to pages by using Page Designer or by creating additional input when you transform your forms. Whichever method you choose, each FactBox must be based on a separate page. You can create a specific page for this purpose, or use an existing page as a FactBox.

For example, the Customer List page contains a FactBox called Customer Sales History - Sell to Customer. This FactBox is based on page 9080 Sales Hist. Sell-to FactBox, which was designed to be used as a FactBox.

This topic describes how to add a FactBox to a page during form transformation.

There are two types of FactBoxes that you can choose from:

  • Page - A page that was either created specifically to be used as a FactBox or is a regular page in the application.

  • System - A predefined, generic object in the RoleTailored client. The following are the types of System FactBoxes:

    • MyNotes

    • Notes

    • Outlook

    • RecordLinks

When you run your form transformation, remember to include any FactBox forms.

The following illustration shows the FactBox - FactBoxes window with FactBoxes added to form 42, Sales Order.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command or by adding forms manually. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

  • Confirm that the page that you will specify as the FactBox exists.

Adding FactBoxes

To add a FactBox to a page

  1. In the Transformation Forms window, select a form to which you want to add a FactBox, click Input, point to Add, and then click FactBoxes.

  2. In the FactBox - FactBoxes window, in the PartType field, select either Page or System for the type of FactBox that you want to add.

  3. If you choose Page type, then enter the page ID in the PagePartID field. The Part Name field will be filled in automatically. If you choose System type, select one of the predefined options in the SystemPartID field.

    Note Note

    If the ID that you specify in the PagePartID field is a form in your application, be sure to transform the form to a page. The transformed page will have the same ID as the existing form.

  4. In the SubFormLink field, specify the relationship for linking a record in the page to a record in the FactBox.

  5. (optional) If the FactBox refers to a record in a subform on the page, then specify the ID of the subform control in the ProviderID field.

  6. (optional) In the NewID field, enter the ID that you want the transformation tool to assign to the FactBox. If you do not enter a value, then the tool assigns an ID automatically. For more information, see Transforming Control and Menu IDs.

  7. Select Visible if you want the FactBox to be displayed on the page by default.

  8. Close the FactBox - FactBoxes window to save your changes.

See Also

Tasks

How to: Create a FactBox to Display Customer Data


How to: Add Home Parts to a Role Center By Using Transformation Input

How to: Add Home Parts to a Role Center By Using Transformation Input

The RoleTailored client has two navigation elements: Role Centers and Departments. To use Role Centers in the RoleTailored client, a new type of form, HomePage, and a new element, Home Parts, have been added.

You can add home parts to a Role Center by using Page Designer or by creating additional input when you transform your forms. This topic describes how to add home parts to a Role Center during form transformation.

There are two types of Home Parts that you can choose from:

  • Page - A page that is created specifically for this purpose.

  • System - A predefined, generic object in the RoleTailored client. The following are the types of System Home Parts:

    • MyNotes

    • Notes

    • Outlook

    • RecordLinks

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command, or by adding forms manually. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

For more information Role Centers, see Profiles and Role Centers in the Microsoft Dynamics NAV 2009 Installation and Configuration Help.

To add a Home Part to a Role Center

  1. In the Transformation Forms window, select a Home Page form, click Input, point to Add, and then click HomeParts.

  2. On a new line in the Home Parts window, in the Column field, enter the number of the column where you want the part placed in the Role Center.

  3. In the PartType field, select either System, Page, or Chart from the drop-down list for the type of part that you want to add.

  4. If you selected System in the PartType field, then in the SystemPartID field, select one of the predefined System Home Parts.

  5. If you selected Page in the PartType field, then in the PagePartID field, enter the ID for the page that you want to add as a Home Part.

  6. If you selected Page in the PartType field, then in the PageName field, enter the name of the page that you want to add. Use the arrow to show the name of the form ID that you entered in the PagePartID field.

  7. (optional) In the NewID field, enter the ID that you want the transformation tool to assign to the home part. If you do not enter a value, then the tool assigns an ID automatically. For more information, see Transforming Control and Menu IDs.

    The following illustration shows the Home Parts window for home page form 9005, Sales Manager Role Center.

    Adding Home Parts by using TIF Editor

  8. Close the Home Parts window to save your changes.


How to: Add Images to the Action Pane by Using Transformation Input

How to: Add Images to the Action Pane by Using Transformation Input

You can add images or icons to the actions that are in the Action Pane and in the menus on a page by using Page Designer or by specifying additional input when you transform your forms. This topic describes how to add an image to an action during form transformation.

The following illustration shows the Add Image by Caption window that is part of the TIF Editor with examples of images added to actions for page 21, Customer Card.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

Adding Images to Actions

To add an image to an action by using the TIF Editor

  1. In the Transformation Forms window, click Input, point to Add by Caption, and then click Image to Action.

  2. In the Add Image by Caption window, in the CaptionML field, add the CaptionML for the action to which you want to add an image.

    Note Note

    All actions in all forms in the application that have the same value in the CaptionML field will be assigned the image that you add.

  3. In the NewName field, add the name of the image file that you want to add to the action. Use the lookup button to select the image from a list.

  4. Close the Add Image by Caption window to save your changes.

    Note Note

    If you want to add a big image to an action, after you have added the image by using the steps in this procedure, go to the Page Actions window and specify Yes in the Promoted is Big field. For more information, see How to: Promote Actions to the Action Pane By Using Transformation Input.

    Note Note

    If you want to assign a big image to all actions with a specific caption, use the Big Image to Action function under Add by Caption in the Input menu. For example, all actions with caption Post have a big image.


How to: Add Shortcuts to New Commands

How to: Add Shortcuts to New Commands

You can add or change a shortcut key for a new command that you have added to a form. For example, in the RoleTailored client, from the General Journal Batches page, you can select a journal in the list and press ENTER to go to the journal page. To add this shortcut to the page, you must add the shortcut to the transformation input. You can add a shortcut to the transformation input by using the Transformation Input File (TIF) Editor or by modifying the transformation input .xml files directly. The following procedure describes how to add a shortcut by using the TIF Editor. For more information about modifying the transformation input .xml files directly, see Understanding Form Transformation Input Files.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

To add a shortcut to a new command

  1. In the Transformation Forms window, click Input, point to Add by Caption, and then click Shortcut to Action.

  2. In the Add Shortcut by Caption window, in the CaptionML column, either find the CaptionML in the list or enter a new CaptionML property of a command for which you want to add a shortcut.

    Note Note

    If you have not imported transformation input files, the Add Shortcut by Caption window will not display a list of CaptionML properties in the CaptionML column.

  3. In the NewName column, add the new shortcut key.

    The following illustration shows an example of the Add ShortCut by Caption window.

    Add ShortCut-MoveElements in TIF Editor

  4. Close the Add Shortcut by Caption window to save your changes.


How to: Change the Menu Where an Action Resides

How to: Change the Menu Where an Action Resides

By default, when forms are transformed, actions are moved to the Related Information menu. To change the menu where an action is placed, use the following procedure.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

Changing the Menu of Actions

To change the menu of an action

  1. In the Transformation Forms window, click Input, point to Move, and then click Action by Caption.

  2. In the Move Action by Caption window, in the CaptionML column, find the action that you want to move to a different menu, or add a new line and enter the CaptionML property of an action.

    Note Note

    All actions in all forms in the application that have the same value in the CaptionML field will be moved to the menu that you specify.

  3. In the destinationType column, select one of the following from the drop-down list:

    • ActionItems

    • Reports

    If you select ActionItems, the action will reside in the Actions menu. If you select Reports, the action will reside in the Reports menu.

  4. Close the Move Action by Caption window to save your changes.

See Also

Concepts

Understanding Form Transformation Input Files
Control Mapping Rules


How to: Exclude Specific Controls from Transformation

How to: Exclude Specific Controls from Transformation

Some forms may have controls that you do not want to include on the transformed page. For example, the Sales Order form has an InfoPane form and a Post/City Code label on each of the three tabs. These controls are not transformed to the Sales Order page. They are excluded from transformation. The following illustration shows the Delete Page Elements window specifying four controls from form 42, Sales Order.

You can exclude certain controls from being transformed onto a page by creating additional input when you transform your forms.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

To exclude specific controls from transformation

  1. In the Transformation Forms window, select a form on which there are one or more controls that you want to exclude from transformation, click Input, and then click Delete Page Control.

  2. In the Delete Page Elements window, in the ControlID field, enter the ID of the control that you want to exclude from transformation.

    Note Note

    If you use the Microsoft Dynamics NAV Developers Toolkit with the TIF Editor, you can use the lookup function from the ControlID field in the Delete Page Elements window. You can find the Microsoft Dynamics NAV Developers Toolkit on PartnerSource.

  3. Close the Delete Page Elements window to save your changes.


How to: Mark Labels on Dialogs as Instructions

How to: Mark Labels on Dialogs as Instructions

Some forms, such as confirmation and dialog forms, include instructional text. Before you transform these forms to pages, you must set the Instructional Text property on instructional text label controls so that the controls will be transformed correctly.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

To mark a label as instructional text

  1. In the Transformation Forms window, select a form which has instructions to the user, typically found on confirmation dialogs, click Input, point to Add, and then click New Control Property.

  2. In the Move Page Elements window, on a new line, in the Group field, select Instructional TextML from the drop-down list.

  3. In the ControlID field, enter the ID of the control that you want to mark as instructional text.

  4. Close the Move Page Elements window to save your changes.


How to: Modify Shortcut Keys

How to: Modify Shortcut Keys

Several shortcut keys have changed in the RoleTailored client in Microsoft Dynamics NAV 2009. These shortcut keys have changed for two reasons:

  1. To avoid conflicts with shortcut keys in the Windows operating system.

  2. To align with shortcut keys in the Windows operating system.

For example, in the Classic client, to insert a new item, you press F3. Generally, in the Windows operating system, F3 is used to search. In the RoleTailored client, to insert a new item, you can either press CTRL+N, or you can press F8. In the RoleTailored client, F3 is used to search.

To add or change shortcut keys in the RoleTailored client, use the following procedure.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

For more information about shortcut keys in the Classic client and in the RoleTailored client, see the Keyboard Shortcuts topic in the Microsoft Dynamics NAV 2009 RoleTailored Client Help.

Modifying Shortcuts

To change a shortcut in the Classic client to a different shortcut in the RoleTailored client, use the following procedure.

To modify shortcut keys

  1. In the Transformation Forms window, click Input, point to Move, and then select Shortcuts.

  2. In the Shortcuts – Move Elements window, in the Name column, enter the shortcut key that you want to change or modify.

    Note Note

    The shortcut keys in the ShortCuts – Move Elements window apply to the entire client application. They are not specific to any one form.

  3. In the NewName column, enter the new shortcut key.

    Note Note

    If the NewName column is blank, then the same shortcut that is in the Name column will be used in the RoleTailored client.

    The following illustration shows an example of the ShortCuts - Move Elements window.

    ShortCuts - Move Elements window in TIF Editor

  4. Close the Shortcuts - Move Elements window to save your changes.


How to: Promote Actions to the Action Pane By Using Transformation Input

How to: Promote Actions to the Action Pane By Using Transformation Input
See Also

Promoting an action adds the action to the Action Pane. If you use a command regularly, you may want to promote it. This gives it a more prominent position on the page. For example, on the Customer List page, Cash Receipt Journal and Customer Top 10 List appear on the Action Pane as promoted actions because the user needs quick access to these items.

Promoted actions are grouped on the Action Pane under the following default Action Pane groups:

  • New

  • Process

  • Reports

You can add promoted actions to pages by using Page Designer or by creating additional input when you transform your forms. You can promote existing actions on the page or you can add new actions to a page and promote them.

Note Note

You cannot create a new Action Pane group by using the form transformation tool. You must use Page Designer to create new Action Pane groups. For more information, see How to: Define Promoted Action Categories Captions for the Action Pane.

This topic describes how to add a promoted action to a page during form transformation. The following illustration shows the Page Actions window, which is part of the Transformation Input File (TIF) Editor, with promoted actions for form 18, G/L Account List.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command or by adding forms manually. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

Adding Promoted Actions

To add a promoted action to a page by using the TIF Editor

  1. In the Transformation Forms window, select a form to which you want to add a promoted action, click Input, point to Add, and then click New and Promoted Actions.

  2. In the Page Actions window, select the action that you want to promote and then select the Promoted field to add a check mark to the field.

  3. If you want the icon for a promoted Action to appear even more prominently in the Action Pane, select Yes in the PromotedIsBig field.

  4. Close the Page Actions window to save your changes.

See Also

Tasks

How to: Add Actions to a Page By Using Transformation Input
How to: Add Images to the Action Pane by Using Transformation Input
How to: Add Actions to the Action Pane on Pages


How to: Promote a Field to the FastTab Header By Using Transformation Input

How to: Promote a Field to the FastTab Header By Using Transformation Input

In the RoleTailored client, you can expand and collapse FastTabs. If you collapse a FastTab, some information from the FastTab will be displayed in summary form on the collapsed tab. To specify which fields are displayed when the FastTab is collapsed, you must set the PromotedField property.

To specify which fields are displayed when the FastTab is collapsed, you can either use Page Designer or you can set the PromotedField property in the input to form transformation. This topic describes how to set the PromotedField property on a field during form transformation.

The following illustration shows the Move Page Elements window, which is part of the Transformation Input Files (TIF) Editor, with several controls on form 21, Customer Card specified as promoted.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

To promote a field to the FastTab header by using the TIF Editor

  1. In the Transformation Forms window, select a form to which you want to promote a field to the FastTab header, click Input, point to Add, and then click New Control Property.

    Note Note

    Typically, you add promoted fields to card or document forms, not to list forms.

  2. In the Move Page Elements window, in the Group field, select PromotedField from the drop-down list.

  3. In the ControlID field, enter the ID of the control that you want to display on the collapsed FastTab.

  4. Close the Move Page Elements window to save your changes.


How to: Set the FixedLayout Property

How to: Set the FixedLayout Property

On forms which have label controls that represent column headers or have a matrix-like layout of controls, you must ensure that fields on the transformed page are displayed in the same layout as on the original form. To do this, you must set the FixedLayout property on the label controls that represent column headers. You can set the FixedLayout property in the Transformation Input File (TIF) Editor so that fields on the transformed page will be displayed correctly.

An example of a form in the standard application that has label controls that represent column headers on which you must set the FixedLayout property is form 39, General Journal. The label controls for Account Name, Bal. Account Name, Balance, and Total Balance have the FixedLayout property set in the standard application transformation input files.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

To set the FixedLayout property

  1. In the Transformation Forms window, select the form that has a matrix-like layout of controls on which you want to set the FixedLayout property on label controls, click Input, point to Add, and then click New Control Property.

  2. In the Move Page Elements window, in the Group field, select FixedLayout from the drop-down list.

  3. In the ControlID field, enter the ID of the control on which you want to set the FixedLayout property.

  4. Close the Move Page Elements window to save your changes.

See Also

Concepts

Arranging Fields in Rows and Columns Using a FixedLayout Control


How to: Specify TabControl IDs By Using Transformation Input

How to: Specify TabControl IDs By Using Transformation Input

Note Note

This topic applies only to Microsoft Dynamics NAV 2009 SP1. For more information about the hotfix for the RTM version of Microsoft Dynamics NAV 2009, see Hotfix on PartnerSource.

In some cases, you may want to specify control and action IDs instead of allowing the form transformation tool to automatically assign IDs. To specify control and action IDs, you must modify the MoveElements.xml file or the TransformPages.xml file, which are two of five transformation input files (TIF).

This procedure describes how to use the TIF Editor to specify the ID of a FastTab that is transformed from the TabControl on a form. For more information about how to specify the ID of an action, see How to: Add Actions to a Page By Using Transformation Input. For more information about how to specify the ID of a FactBox, see How to: Add FactBoxes to Pages By Using Transformation Input. For more information about how to specify the ID of a Home Part, see How to: Add Home Parts to a Role Center By Using Transformation Input.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

To specify a control ID for a TabControl

  1. In the Transformation Forms window, select a form for which you want to specify a TabControl ID, click Input, point to Add, and then click New IDs in TabControl.

  2. In the New ID in TabControl window, do the following:

    1. In the Control ID field, specify the ID of the TabControl on the form.

    2. In the PageNamesML field, specify the PageNamesML value for the tab on the TabControl that will be transformed to a new FastTab on a page. For example, enter ENU=TabName.

    3. In the NewID field, specify the ID that you want to assign to the new FastTab control.

  3. Close the New ID in TabControl window to save your changes.

See Also

Concepts

Transforming Control and Menu IDs
Understanding Form Transformation Input Files


How to: Validate Form Transformation

How to: Validate Form Transformation

Before you export transformation input specifications from the Transformation Input File (TIF) Editor, you can validate the input that you have specified in the TIF Editor. If validation finds any issues, you can fix them before you export the files.

Before you begin this procedure, you must do the following:

  • Install the TIF Editor. For detailed steps, see How to: Install the Transformation Input File Editor.

  • Add your forms to the TIF Editor, either by importing the transformation input files for the standard application forms, or by using the Get Forms command. For more information, see the following topics:

    • How to: Import Transformation Input Files

    • How to: Get Forms in the Transformation Input File Editor

  • Import the list of form types, definitions, and their matching page types that you will use for lookup. For more information, see How to: Import Form to Page Mappings.

To validate the form transformation

  1. In the Transformation Forms window, click Functions, and then click Validate.

  2. In the Page Validation Entries window, review and resolve any errors or warnings before you export the transformation input files. The errors and warnings are the same that you would see in the form transformation log output file if you were to export the transformation input files from the TIF Editor and run the transformation tool. For more information about errors and warnings, see Reviewing the Form Transformation Log Output File.


How to: Export Files from the Transformation Input File Editor

How to: Export Files from the Transformation Input File Editor

After you have specified the transformation input by using the Transformation Input File (TIF) Editor, you must generate the files that will be used as input to the form transformation tool.

Depending on the scope of your input specifications, you must generate all five or fewer files. For more information about the specifications that each input file contains, see Understanding Form Transformation Input Files.

Before you begin this procedure, you must do the following:

  • Install the TIF Editor. For more information, see How to: Install the Transformation Input File Editor.

  • If you have forms that are based on the standard application forms, import the standard application input files. For more information, see How to: Import Transformation Input Files.

  • If you have forms that are not based on the standard application forms, then add these forms to the TIF Editor. For more information, see How to: Get Forms in the Transformation Input File Editor.

  • If you have forms that are not based on the standard application forms, then import the list of form types, definitions, and their matching page types that you will use for lookup. For more information, see How to: Import Form to Page Mappings.

  • Confirm that every form that you want to transform has the page type specified. For more information, see How to: Specify PageType.

  • Confirm that every list form that you want to transform that has an associated card form has the CardFormID specified. For more information, see How to: Specify CardFormID.

  • Define additional input specifications for the form transformation tool. For more information, see Specifying Form Transformation Rules with the Transformation Input Files Editor.

  • (optional) Validate the form transformation. For more information, see How to: Validate Form Transformation.

To export files from the TIF Editor

  1. In the Transformation Forms window, select the forms for which you want to export specifications from the TIF Editor.

  2. In the Transformation Forms window, click Setup, and then click Transformation Setup Card.

  3. In the Transformation Setup window, under TIF path Export, verify the path to which the transformation input files will be exported, and then close the window.

  4. In the Transformation Forms window, click Functions, and then click Create All Transformation Input.

    Note Note

    To create the transformation input files one at a time, click Functions, click Create Transformation Input, and then select one of the transformation input files.


Evaluating Client Files and Automation

Evaluating Client Files and Automation

Before you move to the three-tiered architecture in Microsoft Dynamics NAV 2009, you must evaluate your files that reside on the client to determine whether you need to use different functions to upload or download those files. You must also evaluate your automation components to determine whether you need to use different functions, change code, or redesign them.

Files

In the Classic client, if the application creates a file, then that file is created on the local client computer. In the RoleTailored client, if the application creates a file, the file is created on Microsoft Dynamics NAV Server. If you need to store a file on the client computer, then you must write code to download the file from Microsoft Dynamics NAV Server to the client. Similarly, if the application must access a file that is stored on the client, then you must write code to upload the file from the client to Microsoft Dynamics NAV Server.

The following examples demonstrate scenarios that access files:

  • Reports or batch jobs in which the output is saved to a file

  • COM components that generate or consume files

The following table describes guidelines to determine what you must modify to work with files in the RoleTailored client.

Description of file | Change required
File is used for processing only | No change required.
File is generated on the server and is provided to the user | Use the DOWNLOAD Function (File) or the DOWNLOADFROMSTREAM Function (File) in C/AL.
File is provided from the client and sent to the server | Use the UPLOAD Function (File) or the UPLOADINTOSTREAM Function (File) in C/AL.

Automation Components

The following table describes guidelines to determine if you must modify your automation components for use in the RoleTailored client.

Description of automation component | Change required
Component contains no UI and no client interaction and is for processing only | No change is required.
Component contains no UI and makes a file for a client | Use guidelines for files (see preceding table).
Component contains no UI and accesses local software or network resources, such as MSMQ | You may need to change code to make the computer resource path more explicit.
Component accesses client-local resources, for example, a Gantt server, or client-local hardware, for example, electronic scales | Component is not supported for use with the RoleTailored client. You must redesign using Web services. For more information, see Working with Web Services.

See Also

Reference

DOWNLOAD Function (File)
DOWNLOADFROMSTREAM Function (File)
UPLOAD Function (File)
UPLOADINTOSTREAM Function (File)

Concepts

Working with Web Services


Transforming Forms

Transforming Forms

The transformation process has two stages:

  • Preparing for transformation

  • Transforming forms

The following illustration shows the process of transforming forms to pages.

The topics in this section provide an overview of the steps that you need to take to transform forms to pages. The steps to transform forms are the following:

  1. Export your existing forms to an .xml source file. For more information, see How to: Create the Forms.xml Source File.

  2. (optional) Export the translation strings to a .txt file. For more information, see How to: Create the PageTranslations.txt File.

  3. Configure the log file settings and the input and output file locations. For more information, see Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File.

  4. Run the tool. For more information, see How to: Run the Form Transformation Tool.

  5. Review the log file. For more information, see Reviewing the Form Transformation Log Output File.

  6. If any forms did not transform successfully, then you may need to make changes to your source forms or to the input files and then retransform the forms. For more information, see How to: Retransform Forms.

  7. Import and compile the transformed pages. If any pages do not compile successfully, then you may need to make changes to your source forms or to the input files and then retransform the forms. For more information, see How to: Import, Compile, and Run Transformed Pages.

  8. Run the compiled pages in the RoleTailored client. If any pages do not look the way that you want them to look, then you may need to make changes to your source forms or to the input files and then retransform the forms. For more information, see How to: Run a Page.

  9. (optional) Transform the navigation pane in the Classic client to Departments in the RoleTailored client by transforming the MenuSuite object. For more information, see How to: Transform MenuSuite Objects.

See Also

Concepts

Preparing to Transform Forms to Pages


How to: Create the Forms.xml Source File

How to: Create the Forms.xml Source File

To transform forms to pages, you must create a source .xml file of the forms that you want to transform. The form transformation tool uses this source file as well as the transformation input .xml files and the schema files to transform forms to pages. This procedure describes how to create the source forms .xml file.

Before you begin this procedure, confirm that you have completed the necessary preparation for transforming forms. For more information, see Preparing to Transform Forms to Pages.

To create forms.xml input file

  1. In the Classic client, click Tools, and then click Object Designer.

  2. In Object Designer, click Form.

  3. Select the forms that you want to transform.

  4. Click the File menu, and then click Export.

  5. In the Export Objects window, browse to the location where you want to export the forms. We recommend that you export forms to the same folder where the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file and the transformation input files reside.

  6. In the File name text box, specify the name of the file. We recommend that you name the file Forms.xml.

  7. In the Save As Type drop-down list, select XML Format (*.xml), and then click Save.

    Note Note

    After you have saved the forms to the Forms.xml file, you must configure the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file. When you configure this file, verify that it specifies the correct name and location for the exported forms XML file. For more information, see Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File.

See Also

Concepts

Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File


How to: Create the PageTranslations.txt File

How to: Create the PageTranslations.txt File

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Some page content in multilanguage applications originates from forms or transformation input that has not been translated. To preserve the translations for all page content, you must export the translation strings from your application to a text file. The transformation tool uses this translation file as input. After creating transformed pages, the transformation tool adds any translated strings from the translation file to the CaptionML properties of page controls.

If you do not specify a translation file, then the transformation tool does not add any translated strings to pages.

Before you begin this procedure, verify that you have completed the necessary preparation for transforming forms. For more information, see Preparing to Transform Forms to Pages.

To create PageTranslations.txt file

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Page.

  3. Select the pages for which you want to export translation strings.

  4. On the Tools menu, point to Translate, and then click Export.

  5. In the Translate Export window, browse to the location where you want to export the translation file. We recommend that you export files to the same folder where the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file and the transformation input files reside.

  6. In the File name text box, specify the name of the file. We recommend that you name the file PageTranslations.txt.

  7. In the Save As Type drop-down list, select Text Files (*.txt), and then click Save.

    Note Note

    After you have exported the translation file, the next step in the transformation process is to configure the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file. When you configure this file, verify that it specifies the correct name and location for the translation file. For more information, see Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File.

See Also

Concepts

Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File


Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File

Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File
See Also

Use the form transformation configuration file, Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config, for the following purposes:

  • To define file names and path locations for input and output files. The form transformation tool references these files during execution.

  • To define the scope of logging by specifying what types of exceptions you want to include in the output log file.

If you have saved your files to the default locations and if you want to use the default scope of logging, then you do not need to modify the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file.

File Locations

By default, the location of the input and output files is the same as the location of the tool. The configuration file contains the following lines, which specify the names and locations for input and output files.

CopyCode image Copy Code
<configuration>
  <appSettings>
    <add key="FormsFile" value=".\Forms.xml"/>
    <add key="PagesFile" value=".\Pages.xml" />
    <add key="IgnorePages" value=".\IgnorePages.xml"/>
    <add key="MovePages" value=".\MovePages.xml"/>
    <add key="TransformPages" value=".\TransformPages.xml"/>
    <add key="DeletePageElements" value=".\DeleteElements.xml"/>
    <add key="MovePageElements" value=".\MoveElements.xml"/>
    <add key="CodeRules" value=".\coderules.txt"/>
    <add key="TranslationFile" value=".\PageTranslations.txt"/>
    <add key="SchemasPathLocation" value =".\"/>

You can change this information in the configuration file if you want to use input files from a different folder or if you change the names of the input or output files.

Scope of Logging

You can control the size and focus of your log file by including only the exceptions in which you are most interested. The following table describes the exception message types.

Message Type | Description
ChangeCodeManually | Transformation of a specified control or property could not be completed. Additional, typically manual, change or input is required to address the exception that is associated with this message.
CheckInputFile | There is an inconsistency in an input file.
CodeCannotBeTransformed | Code cannot be transformed automatically. Manual change to the form itself is needed.
Error | Any error. Typically, the transformation tool cannot recover after such an error.
General Information | Any information. Typically, no action is required.
IgnoreForms | Specified form was excluded from the transformation and no matching page was created.
IgnoreWarning | Verify that there is not an issue, and then ignore this warning.
InputInformation | Information about input files.
RemoveControls | Specified control on the form was not mapped to a matching control on a page.
ValidateManually | Specified control or code has been changed during transformation. The change requires manual validation.
Warning | Any warning. Requires manual validation.

To configure which type of messages to include in the log file and the degree of message details, you assign a value code to each message type in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file, and then set the TraceLevelSwitch value to specify the logging level.

The following example from the configuration file shows the default value code assignments for each message type.

CopyCode image Copy Code
      <add name="Error" value="1" />
      <add name="CodeCannotBeTransformed" value="1" />
      <add name="Warning" value="2" />
      <add name="GeneralInformation" value="4" />
      <add name="IgnoreForms" value="3" />
      <add name="IgnoreWarning" value="2" />
      <add name="InputInformation" value="1" />
      <add name="RemoveControls" value="3" />
      <add name="ChangeCodeManualy" value="2" />
      <add name="ValidateManualy" value="3" />
      <add name="CheckInputFile" value="1" />

Based on the preceding value codes, the default logging levels can be described as follows:

  • 1 Logs error messages and required information

  • 2 Logs errors and warnings

  • 3 Logs detailed error information

  • 4 Logs verbose information

  • 0 Logging is turned off

To specify the level of logging, you set the TraceLevelSwitch value. For example, in the following code, the logging level is set to 1, log error messages and required information.

CopyCode image Copy Code
      <add name="TraceLevelSwitch" value="1" />

You can modify the level of logging or the value code for each message type in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file.

See Also

Tasks

How to: Run the Form Transformation Tool


How to: Run the Form Transformation Tool

How to: Run the Form Transformation Tool

The following procedure describes how to run the form transformation tool to transform forms for the Classic client to pages that you can use in the RoleTailored client.

Before you begin this procedure, you must do the following:

  • Complete the necessary preparation for transforming forms. For more information, see Preparing to Transform Forms to Pages.

  • Create the source forms.xml file. For more information, see How to: Create the Forms.xml Source File.

  • Configure the input and output file locations and the level of logging. For more information, see Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File.

Running the Form Transformation Tool

To run the form transformation tool

  1. Confirm that you have the following input files, and that the path to these input files is correct in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file:

    • Forms.xml

    • CodeRules.txt

    • TransformPages.xml

    • IgnorePages.xml

    • MovePages.xml

    • DeleteElements.xml

    • MoveElements.xml

    • DeletePageElement.xsd

    • IgnorePage.xsd

    • MovePage.xsd

    • MovePageElement.xsd

    • TransformationInput.xsd

    • Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config

    • Microsoft.Dynamics.Nav.Tools.FormTransformation.exe

  2. Navigate to the folder where Microsoft.Dynamics.Nav.Tools.FormTransformation.exe is located.

  3. Double-click Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.

  4. Verify that the tool completes successfully and that you have the following output files in the folder specified in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file:

    • Pages.xml

    • Transformation.log

    • TransformationLog.xml (contains the same information as Transformation.log)

After you run the transformation tool, you must complete the following steps:

  • Inspect the log file for errors. For more information, see Reviewing the Form Transformation Log Output File.

  • If necessary, re-transform all or selected forms. For more information, see How to: Retransform Forms.

  • Import and compile pages. For more information, see How to: Import, Compile, and Run Transformed Pages.


Reviewing the Form Transformation Log Output File

Reviewing the Form Transformation Log Output File

After you run the form transformation tool, the pages that the tool created might not contain functionality that is equivalent to the original forms and might not display correctly in the user interface. You can use the information captured in the log file to help you to diagnose problems. By inspecting the log file, you can identify issues before you deploy the new page objects in the RoleTailored client. To resolve these issues, you must modify the input to the form transformation tool and run the tool again.

This topic describes the information that is in the transformation log files. The same information is captured in the following log files:

  • Transformation.log

  • TransformationLog.xml

For detailed steps about re-running the transformation tool, see How to: Retransform Forms.

Log File Message Types

The following table describes each of the message types in the log file.

Message type | Description
ChangeCodeManually | Transformation of a specified control or property could not be completed. Additional, typically manual, change or input is required to address the exception that is associated with this message.
CheckInputFile | There is an inconsistency in an input file.
CodeCannotBeTransformed | There are issues with code transformation.
Error | Any error. Typically, the transformation tool cannot recover after such an error.
GeneralInformation | Any information. Typically, no action is required.
IgnoreForms | Specified form was excluded from the transformation and no matching page was created.
IgnoreWarning | Verify that there is not an issue, and then ignore this warning.
InputInformation | Information about input files.
PossibleCompilationProblem | A property or method may not be supported in the RoleTailored client and may not compile.
RemoveControls | Specified control on the form was not mapped to a matching control on a page.
ValidateManually | Specified control or code has been changed during transformation. The change requires manual validation.
Warning | Any warning. Typically, warnings relate to file input/output operations.

Examples

The following examples show code examples from Transformation.log files of each type of log message.

ChangeCodeManually

In this example, the form transformation tool has identified a label on form 5077 that is instructional text but is not marked as such. To resolve this message, you must mark the label as an instruction. For more information, see How to: Mark Labels on Dialogs as Instructions.

CopyCode image Copy Code
ChangeCodeManually: Form 5077: Parentless label 14 ("ENU=When you click
Next, if your interaction template is set up to:") was found.
If this label should be treated as Instructional Text,
please mark it as InstructionalTextML in file:///C:/transformation/NDBC/MoveElements.xml

CheckInputFile

In this example, the action with ID 20 on form 1004 exists in the Forms.xml file but does not exist in the TransformPages.xml input file.

CopyCode image Copy Code
CheckInputFile: Form 1004: The ID 20 from the transformation input file, do not exist in the input xml file.

In this example, the DeleteElements.xml file is not found at the location that is specified in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file.

CopyCode image Copy Code
CheckInputFile: Could not load .\DeleteElements.xml

Error

In this example, the form transformation tool cannot open the source Forms.xml file.

CopyCode image Copy Code
Error: Could not load .\Forms.xml
Error: Transformation aborted

In this example, there is an error with form 591.

CopyCode image Copy Code
Error: Form 591: Manage Option Buttons.....
Error: Form 591: startIndex must be less than length of string.

General Information

This message type is for internal use only. No action is required.

IgnoreForms

In this example, form 64 is ignored. This form was listed in the IgnorePages.xml input file. In this example, there was an error in the logging and the reason for the error is not given.

CopyCode image Copy Code
IgnoreForms: Form 64: Ignored, due to a {0}

IgnoreWarning

In this example, the label, whose ID is 6 on form 342, is ignored.

CopyCode image Copy Code
IgnoreWarning: Form 342: Label 6. Property Name will be ignored.

InputInformation

CopyCode image Copy Code
------------ Transformation started at 14-07-2008 15:05:30 ------------
Forms file: .\Forms.xml
Pages file: .\Pages.xml
InsertElements file: .\TransformPages.xml
IgnoreForms file: .\IgnorePages.xml
DeleteElements file: .\DeleteElements.xml
MoveElements file: .\MoveElements.xml
RenumberPages file: .\MovePages.xml
CodeRules file: .\coderules.txt
-----------------------------------------------------------------------

PossibleCompilationProblem

In this example, EDITABLE is not supported on the RoleTailored client and is not included in CodeRules.txt file:

CopyCode image Copy Code
Property or method EDITABLE may not be supported in the RoleTailored client. The following code may not be compiled:
BEGIN
  CurrPage.Field.EDITABLE(NOT("Unit Cost (LCY)" = 0));
END;
Analyze your code and add a new rule to the CodeRules.txt file if necessary.:

RemoveControls

In this example, the log file specifies that several controls were removed from form 317.

CopyCode image Copy Code
RemoveControls: Form 317: Buttons: OK/Cancel, Yes/No, LookupOK, LookupCancel, and Close. CommandButton control <30> will be removed.

ValidateManually

CopyCode image Copy Code
ValidateManually: Form 151: TextBox as Label found (by X/Y position).
TextBox ID 14 recognized as Label.
Source Expression (FORMAT (STRSUBSTNO(Text000,FORMAT(CurrentDate)))) moved to
CaptionClass of control ID 15.

ValidateManually: Form 99000833: CaptionML value (ENU=This Sales Line is currently planned.
Your changes will not cause any replanning. Do you still want to record the changes?)
for control id 2 was moved to variable Text000@1008.
This variable was assigned to CaptionClass property.

Warning

CopyCode image Copy Code
Warning: Form 317: Control with property password has been transformed
into a masked text extended data type. This is not a secure solution.
If this control is going to be used for entering passwords or other
secure data you have to develop a secure solution to support this.

See Also

Tasks

How to: Retransform Forms

Concepts

Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File


How to: Retransform Forms

How to: Retransform Forms

Form transformation is an iterative process. After you run the form transformation tool, you might discover errors or warnings in the transformation log file or issues with the page in the RoleTailored client. If the first transformation does not successfully convert all your forms into pages, then you need to make changes and run the transformation tool again.

Before you begin this procedure, be sure that you have reviewed the Transformation.log file and that you understand any errors or warnings. For more information, see Reviewing the Form Transformation Log Output File.

To retransform forms

  1. If needed, make changes to the source form objects. For more information, see Preparing for Form Transformation by Redesigning Forms.

  2. If needed, make changes to the transformation input files. For more information, see Preparing Transformation Tool Input.

  3. If you have modified any source form objects, re-create the Formsl.xml source file. For more information, see How to: Create the Forms.xml Source File.

  4. Re-run the tool until you have transformed all your forms successfully. For more information, see Transforming Forms.

See Also

Concepts

Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File


How to: Import, Compile, and Run Transformed Pages

How to: Import, Compile, and Run Transformed Pages

After you have run the form transformation tool, you must import the Pages.xml file into Object Designer. Pages.xml contains all the metadata required to display your transformed forms as pages in the RoleTailored client. You must also compile all of the new page objects so they are compatible with the .NET Framework and the Microsoft Dynamics NAV architecture. After you import and compile the transformed pages, the Microsoft Dynamics NAV database contains both your original Classic client forms and your new page objects. You can run the RoleTailored client and view the transformed pages.

Before you begin this procedure, you must successfully run the form transformation tool. For more information, see How to: Run the Form Transformation Tool.

To import, compile, and deploy transformed pages

  1. In the Classic client, click Tools, and then click Object Designer.

  2. Click the File menu, and then select Import.

  3. In the Import Objects window, in the Files of type drop-down list, select XML Format (*.xml), browse to the folder where the Pages.xml file is located, select Pages.xml, and then click Open.

    Note Note

    By default, the Pages.xml file, which was created when you ran the form transformation tool, is located in the same folder as the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file and the transformation input files. If you changed the name or the location of the output .xml file in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file, select the name of the file that you specified.

  4. In Object Designer, click Page, and then select all the pages that you imported.

  5. From the Tools menu, select Compile, and then click Yes.

  6. Run the transformed pages in the RoleTailored client. For more information, see How to: Run a Page.


Transforming MenuSuite Objects

Transforming MenuSuite Objects

In the Classic client, you access forms and reports from the navigation pane, which displays menus that are contained in a MenuSuite object. In the RoleTailored client, you navigate to pages and reports by using the following elements:

  • Role Centers

  • Departments

You can transform a MenuSuite object that you use in the Classic client to a Departments page that you use in the RoleTailored client.

The Departments page contains the entire suite of functionality as licensed and available to the company. In this way, the Departments page in the RoleTailored client is similar to the navigation pane in the Classic client. The Departments page is also a MenuSuite object with a layered item structure but is designed specifically for the RoleTailored client.

In Microsoft Dynamics NAV 2009, when you create a new MenuSuite object, you must select either the Classic client or the RoleTailored client as the target.

Note Note

If you support both the Classic client and the RoleTailored client, you must maintain two sets of MenuSuite objects.

The ID of a MenuSuite object for the RoleTailored client will be the Classic client ID plus 1000, as demonstrated in the following table.

MenuSuite object in the Classic client | MenuSuite object in the RoleTailored client
10 MBS | 1010 Dept - MBS
51 Add-on 1 | 1051 Dept - Add-on 1

You transform a MenuSuite object by using the Transformation Input File (TIF) Editor. The MenuSuite transformation creates a suggestion for a Departments page that is based on the navigation pane, transformation rules, and input.

After you transform the MenuSuite object, you must verify whether you need to make additional updates to the transformed Departments page. The RoleTailored client has different functionality and different user experience (UX) requirements than the navigation pane in the Classic client. The additional updates that you make to the transformed Departments page can take advantage of the new functionality. For more information about the UX guidelines in Microsoft Dynamics NAV 2009, see User Experience Guidelines for Microsoft Dynamics NAV 2009.

To reduce the number of these manual updates that you have to make after transformation, verify that you meet the following conditions before transforming a MenuSuite object.

Condition | Reason
PageType is assigned to all form objects. | Form objects will be placed in a Department Category based on PageType.
CardFormID is assigned to all list form objects with a card. | Card Form IDs in MenuSuite will be replaced with the related list.
Microsoft Dynamics NAV Developer Toolkit is installed to provide data about which reports are ProcessingOnly reports. | ProcessingOnly reports are placed in the Tasks category on department pages. Other reports are placed in the Reports and Analysis category on department pages.

See Also

Tasks

How to: Transform MenuSuite Objects
Touring the RoleTailored Client Windows
Walkthrough: Creating a Role Center

Concepts

MenuSuite Object Fundamentals


How to: Transform MenuSuite Objects

How to: Transform MenuSuite Objects

This procedure describes how to transform a MenuSuite object from the Classic client to a MenuSuite object that you can use in the RoleTailored client.

Before you begin this procedure, you must do the following:

  • Install the Transformation Input File (TIF) Editor. For more information, see How to: Install the Transformation Input File Editor.

  • Read the information in Transforming MenuSuite Objects.

To transform the MenuSuite object

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click MenuSuite, and then select the MenuSuite object that you want to transform.

  3. To export the existing MenuSuite object from Object Designer to a text file, on the File menu, click Export.

  4. In the Export Objects window, select the location where you want to export the MenuSuite object. We recommend that you export the object to the same folder where the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file and the transformation input files reside.

  5. In the Save as type drop-down list, select Text Format (*.txt).

  6. Specify the name of the file, such as navigationpane.txt, and then click OK.

  7. In Object Designer, select Form, select form 177000, Transformation Forms, and then click Run.

  8. In the Transformation Forms window, click Functions, and then click MenuSuite Transformation.

  9. In the MenuSuites window, click Functions, and then click Import to import the navigationpane.txt file into the TIF Editor.

  10. In the Open File window, select the navigationpane.txt file that you created in step 6, and then click Open.

  11. Click Functions, and then click Show Menu to display all objects in the suite and their properties. After you review the objects in the suite, close the MenuNodes window.

    The following figure shows the MenuSuite objects in the TIF Editor.

  12. To transform the MenuSuite, in the MenuSuites window, click Functions and then click Make Suggestion. In the dialog box, click Yes to confirm.

    The following table describes the behavior when you create a suggestion from a MenuSuite object, such as 10 MBS. The source Classic MenuSuite object is never overwritten.

    RoleTailored client MenuSuite object exists Result Example

    No

    New RoleTailored client MenuSuite object created

    1010 MBS created

    Yes

    RoleTailored client MenuSuite object is overwritten with data from the TIF Editor and Microsoft Dynamics NAV Developers Toolkit

    1010 MBS overwritten with new data

  13. In the MenuSuites window, click Functions, and then click Validate to verify the result and find additional actions that you will need to take to modify the transformed MenuSuite object. The BadLink column specifies objects that are not in the database. The Comment column specifies menu items that you must delete manually, such as ignored forms or dataport objects. You will make the required modifications in Navigation Pane Designer after you export the transformed MenuSuite object.

  14. Click Functions, and then click Show Menu. In the Menu Nodes window, note that the following new properties have been added to the items in the MenuSuite:

    • IsDepartment

    • RunObjectType

    • DepartmentCategory

    • New RunObjectID

    If IsDepartment is cleared, then the menu item is a group heading only.

    If IsDepartment is selected, then the menu item or group is a link.

    Card pages are now replaced with list pages as the first access point when accessed from the navigation. This is specified in the Menu Nodes window by the New RunObjectID column, which references a list object, and the Department Category column, which specifies Lists.

  15. To export the new MenuSuite object from the TIF Editor to an object text file, in the MenuSuites window, click Functions, and then click Export.

  16. In the Save File window, select the location where you want to export the new MenuSuite object. We recommend that you export the object to same folder where the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file and the transformation input files reside.

  17. In the Save as type drop-down list, select Text Format (*.txt).

  18. Specify the name of the file, such as departments.txt, and then click Save.

  19. To import the new Departments MenuSuite object, in Object Designer, click MenuSuite, click the File menu, and then click Import.

  20. In the Import Objects window, browse to the location where you created the departments.txt file.

  21. In the Files of type drop-down list, select Text Format (*.txt).

  22. Select departments.txt, and then click Open.

  23. In Object Designer, select the new MenuSuite object, and then click Design. Make any modifications that were specified when you validated the MenuSuite object in step 13, such as deleting ignored forms or dataport objects.

  24. In Object Designer, select the new MenuSuite object, click the Tools menu, and then click Compile. Click Yes to confirm compilation.

  25. To view the transformed MenuSuite object, open the RoleTailored client and then select the Departments page. Verify whether you need to update the Departments page. For example, you may want to move items to other folders, delete folders, or change categories. For more information, see How to: Create and Modify a MenuSuite Object.

See Also

Concepts

Transforming MenuSuite Objects


Walkthrough: Transforming a Standard Application Form

Walkthrough: Transforming a Standard Application Form

In this walkthrough, you will learn how to transform form 21, Customer Card, from a form that you use in the Classic client to a Customer Card page that you can use in the RoleTailored client. Because this form is a standard application form, the transformation includes the changes in the standard application transformation input files and additional changes that are specific to the customer.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Installing the form transformation tool and the Transformation Input File (TIF) Editor

  • Importing the transformation input files for the standard application

  • Modifying the transformation input files by using the TIF Editor

  • Validating form transformation

  • Exporting the transformation input files

  • Transforming the form

  • Importing, compiling, and running the transformed page

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 installed with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements met. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

Expand image Story

Simon is a Microsoft Certified Partner working for CRONUS International. He has been asked to transform the forms for CRONUS International from Microsoft Dynamics NAV 2009 forms to pages so that CRONUS can use the RoleTailored client. He plans to start by transforming the Customer Card form, which is a standard application form, so that he can understand the form transformation process. Simon has been asked to include the following elements on the transformed page:

  • Customer Sales History FactBox

  • Customer Statistics FactBox

  • Icons in the Action Pane for creating new sales invoices, sales orders, and reminders

  • Icons in the Action Pane for applying a template, viewing the cash receipt journal and viewing the customer statistics

  • A big icon in the Action Pane for viewing the sales journal

  • An icon in the Action Pane for viewing the Customer - Balance to Date report

  • FastTabs that include useful information when collapsed, including:

    • Customer number

    • Customer name

    • Contact

    • Phone number

    • E-mail address

    • City

Simon will use the form transformation tool to transform the Customer Card form to the Customer Card page. Simon has chosen to use the TIF Editor to simplify his task of creating the input files for the form transformation tool.

Expand image Installing the Form Transformation Tool and TIF Editor

To install the form transformation tool, you must copy files to the server where you are running Microsoft Dynamics NAV 2009. After you install the form transformation tool, you can install the TIF Editor.

To install the form transformation tool and TIF Editor

  1. Create a folder called FormTransformation on the C: drive of the server running Microsoft Dynamics NAV 2009.

  2. Copy the contents of the TransformationTool folder, which includes the TIF Editor folder, from the installation media.

  3. In the Classic client, on the Tools menu, click Object Designer.

  4. On the File menu, click Import.

  5. In the Import Objects window, select the TIF.fob file, and then click Open.

    Note Note

    The TIF.fob file is located in the TIF Editor folder, which you copied in step 1.

  6. Click Yes to import all objects.

Expand image Importing the Transformation Input Files in the TIF Editor

When you installed the form transformation tool, you copied the following transformation input files for the standard application to your server running Microsoft Dynamics NAV 2009:

  • TransformPages.xml

  • IgnorePages.xml

  • MovePages.xml

  • DeleteElements.xml

  • MoveElements.xml

The form that you want to transform, form 21, Customer Card, is a standard application form. Therefore, the input specifications for transforming this form are contained in the transformation input files for the standard application. Before you transform the Customer Card form, if you want to use the TIF Editor to modify the transformation input files, you must import the standard application transformation input files into the TIF Editor.

To import the transformation input files into the TIF Editor

  1. In Object Designer, click Form, select form 177000, Transformation Forms, and then click Run.

  2. In the Transformation Forms window, click Setup, and then click Transformation Setup Card.

  3. In the Transformation Setup window, under TIF path Import, enter C:\FormTransformation.

  4. Close the Transformation Setup window to save your changes.

  5. In the Transformation Forms window, click Setup, and then click Import All Transformation Input.

Expand image Modifying the Transformation Input Files in the TIF Editor

Now that you have imported the transformation input files for the standard application into the TIF Editor, you can modify the input specifications. Most elements that you have been asked to add to the page are already specified in the standard application transformation input files, so you only need to verify them in the TIF Editor. For any elements that are not already in the standard application transformation input files, you must add to the input specifications.

To modify the transformation input files in the TIF Editor

  1. In the Transformation Forms window, select form 21, Customer Card, click Input, point to Add, and then click FactBoxes.

  2. Verify that the FactBox - FactBoxes window includes the following pages:

    • Part Name field is Sales Hist. Sell-to FactBox and Visible field is selected.

    • Part Name field is Customer Statistics FactBox and Visible field is selected.

  3. Close the FactBox - FactBoxes window.

  4. In the Transformation Forms window, select form 21, Customer Card, click Input, point to Add by Caption, and then click Image to Action.

  5. Verify that the Add Image by Caption window includes lines in which the CaptionML fields are the following values:

    • ENU=Sales Invoice

    • ENU=Sales Journal

    • ENU=Reminders

    • ENU=Apply Template

    • ENU=Cash Receipt Journal

    • ENU=Statistics

  6. Close the Add Image by Caption window.

  7. In the Transformation Forms window, select form 21, Customer Card, click Input, point to Add by Caption, and then click Big Image to Action.

  8. In the Add Big Image by Caption window, on a new line, enter ENU=Sales Journal in the CaptionML field, and then close the Add Big Image by Caption window.

  9. In the Transformation Forms window, , select form 21, Customer Card, click Input, point to Add, and then click New and Promoted Actions.

  10. Verify that the Page Actions window includes a line in which the CaptionML field is ENU=Customer - Balance to Date and the ActionsType field is Reports, and then close the Page Actions window.

  11. In the Transformation Forms window, select form 21, Customer Card, click Input, point to Add, and then click New Control Property.

  12. Verify that the Move Page Elements window includes lines in which the Group field is PromotedField and the ControlID and Description fields are the following values:

    • 2, "No."

    • 4, "Name"

    • 16, "Contact"

    • 103, "Phone No."

    • 107, "E-Mail"

  13. In the Move Page Elements window, on a new line, select PromotedField from the Group drop-down list, enter 10 in the ControlID field, enter "City" in the Description field, and then close the Move Page Elements window.

Expand image Importing Form to Page Mappings

Before you transform a form to a page, you must specify the page type for the transformed page. To simplify the task of specifying page types, you can instead specify the form type for the form that you want to transform, and then import into the TIF Editor a file that maps form types to page types. This mapping file is one of the files that you copied when you installed the form transformation tool.

Because the form type and page type for the Customer Card form are specified in the standard application transformation input files, you do not need to import the mapping file into the TIF Editor for specifying the page type. However, to validate the input specifications, the TIF Editor must have the form-to-page mapping information. Therefore, before you validate, you must import the form-to-page mappings.

To import form to page mappings

  1. In the Transformation Forms window, click Setup, and then click Import FT-PT Mapping.

  2. In the Import/Export Form Types window, in the File Name field, click the ellipsis button (...).

  3. In the Dataport Import File Name window, browse to the C:\FormTransformation\TIF Editor folder, select the FormToPageTypeMapping.txt file, and then click Open.

  4. In the Import/Export Form Types window, under Direction, select Import, and then click OK.

Expand image Validating Form Transformation

Before you export transformation input specifications from the TIF Editor to .xml input files, you can validate the input that you have specified in the TIF Editor. If there are any validation issues, you can fix them before you create the .xml input files.

To validate the form transformation

  1. In the Transformation Forms window, click Functions, and then click Validate.

  2. In the Page Validation Entries window, verify that there are no warnings for PageID 21.

Expand image Exporting Transformation Input Files

Now that you have modified the input specifications in the TIF Editor and validated that input, you must export the input specifications to the transformation input files. The modifications in this walkthrough changed the input specifications in the TransformPages.xml file and the MoveElements.xml file. You must export these two files. The modifications in this walkthrough did not change the input specifications in the IgnorePages.xml file, the MovePages.xml file, or the DeleteElements.xml file. You can use the original standard application files that you copied when you installed the form transformation tool for these unchanged files.

For more information about each of the transformation input files, see Understanding Form Transformation Input Files.

To export the transformation input files

  1. In the Transformation Forms window, click Functions, point to Create Transformation Input, and then click Transform Pages.

  2. In the Save TransformPages window, navigate to the C:\FormTransformation folder, select TransformPages.xml, and then click Save.

  3. In the Transformation Forms window, click Functions, point to Create Transformation Input, and then click Move Page Elements.

  4. In the Save MoveElements window, navigate to the C:\FormTransformation folder, select MoveElements.xml, and then click Save.

Expand image Transforming the Form

To transform a form, you must create a source .xml file of the form. Typically, you also need to verify the form transformation configuration file for file locations and logging level. In this walkthrough, you did not change the file locations or names and you do not need to change the default logging level, so you do not need to verify the configuration file. After you create the source .xml file for the form, you can run the form transformation tool.

To transform the form

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Form.

  3. Select Form 21, Customer Card, click the File menu, and then click Export.

  4. In the Export Objects window, browse to the c:\FormTransformation folder. In the File name text box, enter Forms.xml.

  5. In the Save As Type drop-down list, select XML Format (*.xml), and then click Save.

  6. Navigate to the C:\FormTransformation folder.

  7. Double-click Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.

  8. Verify that the tool completes successfully and that you have the following output files in the c:\FormTransformation folder:

    • Pages.xml

    • Transformation.log

Expand image Importing, Compiling, and Running the Transformed Page

Before you can view the transformed page in the RoleTailored client, you must import the page into Object Designer in the Classic client and compile the page.

To import, compile, and run the transformed page

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. On the File menu, click Import.

  3. In the Import Objects window, in the Files of type drop-down list, select XML Format (*.xml), browse to the C:\FormTransformation folder, select Pages.xml, and then click Open.

  4. In Object Designer, click Page, and then select Page 21, Customer Card.

  5. On the Tools menu, click Compile, and then click Yes.

  6. Type the following command at a command prompt to run the transformed page in the RoleTailored client:

    DynamicsNAV:////runpage?Page=21

Expand image See Also

Concepts

Transforming Forms to Pages
Preparing Transformation Tool Input
Creating and Maintaining Pages


Troubleshooting: Actions That Call Subforms

Troubleshooting: Actions That Call Subforms

The form transformation tool has built-in rules for transforming menu items. The built-in rules specify that a menu item is transformed to the Actions menu on the main page except in the following cases.

  • If the menu item calls a subform and can be moved to the subform without changing functionality, then the menu item is transformed to the subform.

  • If a menu item on the main form calls a subform but the code cannot be moved to the subform without changing the functionality, then the menu item is not moved, and the issue is included in the form transformation log file. To resolve this issue, you must rewrite the code for the menu item.

The following illustration shows a main form that calls a subform. The Get Price function in this form depends on the item that is selected in the line of the subform.

If you have a custom form that has a menu item that depends on the record that is selected in the subform, then you may need to rewrite the code. The following procedure describes how to rewrite code for an action on a main form that calls a subform.

To complete this procedure, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

To modify an action that depends on a subform

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Form, select the subform on which the function that you want to redesign depends, and then click Design.

  3. On the View menu, click C/AL Code.

  4. Find the function that the main form calls. For example, on a form that gets the price of the item that is selected on the subform, you may have a ShowPrices function with an input SalesHeader parameter and with the following code.

    CopyCode image Copy Code
    CLEAR(SalesPriceCalcMgt);
SalesPriceCalcmgt.GetSalesLinePrice(SalesHeader,Rec);

  5. In the View menu, click C/AL Locals. On the Variables tab, create a new local variable called SalesHeader that has a DataType of Record and Subtype of Sales Header. On the Parameters tab, remove the parameter from the function.

  6. In the C/AL Editor, add code that gets the information from the table for the line that is selected in the subform. Now, your modified ShowPrices function has no parameters. It uses the SalesHeader local variable that you created in step 5 instead of using a SalesHeader parameter that is passed to the function. ShowPrices has the following code.

    CopyCode image Copy Code
    SalesHeader.GET("Document Type","Document No.");
CLEAR(SalesPriceCalcMgt);
SalesPriceCalcMgt.GetSalesLinePrice(SalesHeader,Rec);

  7. Close the C/AL Editor.

  8. To close and compile the subform, close the subform in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

  9. In Object Designer, click Form, select the main form that you want to redesign, and then click Design.

  10. In Form Designer, click the Functions command button.

  11. In the View menu, click Menu Items.

  12. In Menu Designer, select the line for the menu item that you want to redesign.

  13. On the View menu, click C/AL Code.

  14. In the OnPush trigger, change the code to call the function that you modified, which does not have any parameters. For example, if you modified the ShowPrices function, then change the following code.

    CopyCode image Copy Code
    // Old code
    SalesHeader.Get("Document Type","No.");
    CurrForm.ShowPrices(SalesHeader);
// New code
    CurrForm.SalesLines.FORM.ShowPrices

  15. Close the C/AL Editor.

  16. To close and compile the subform, close the subform in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

See Also

Tasks

How to: Retransform Forms

Concepts

Reviewing the Form Transformation Log Output File


Troubleshooting: Fields in Columns on a Transformed Page

Troubleshooting: Fields in Columns on a Transformed Page

After you transform a form to a page, you may encounter problems with fields that are displayed in columns. On the form, these columns may designate particular groups. Pages have built-in layout logic and do not require that you manually specify the position of a control on a page. The layout of fields on a page may be different from the layout of the fields on the form. On a form in which the layout in columns is used to designate groups, you can modify the form before you transform it so that you do not lose the groups if the field layout is different on the page.

The following illustration shows a form with fields that are displayed in columns.

If you transform this form, the fields are not displayed in the same columns on the page. The following illustration shows the resulting page if you transform this form.

To resolve this issue, modify the form so that it will retain field groups after it is transformed by doing one of the following:

  • Indent the fields that are in a group and place them under a header

  • Create a frame around the fields that are in a group

To complete this procedure, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

To indent fields and place them under a header

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Form, select the form that you want to modify, and then click Design.

  3. Add a label above the fields that you want to group. This label is the header for the indented group. For more information, see How to: Create Labels.

  4. Indent the label and text box of each field that you want to group. The label must be indented at least 110 pixels and no more than 330 pixels. To indent, right-click the control, and then click Properties. In the Properties window, modify the value of the Xpos field.

    The following illustration shows the transformed page with group labels so that the columns contain the same fields as on the form.

  5. To save and compile your form, close the form in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

To create a frame around fields in a group

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Form, select the form that you want to modify, and then click Design.

  3. Create frames for each group and move the groups of fields into the frames. For more information, see How to: Create a Frame to Contain Controls.

    The following illustration shows the transformed page with frames so that the columns contain the same fields as on the form.

    Note Note

    If you do not want the original form to show the frames, then set the Border property for the frame to No and set the ShowCaption property to No. The transformed page does not show the frames, regardless of the value of the Border and ShowCaption properties.

  4. To save and compile your form, close the form in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

See Also

Tasks

How to: Retransform Forms


Troubleshooting: Labels on a Transformed Page

Troubleshooting: Labels on a Transformed Page

After you transform a form to a page, you may encounter problems with labels that are not transformed correctly or are different than you expect. This issue occurs when labels on a form do not comply with the label control mapping rules in the form transformation tool. For more information about label control mapping rules, see the Label Control section of Control Mapping Rules.

You can resolve these problems by modifying the labels on the form and retransforming the form to a page.

Labels are transformed in the following cases:

  • The label has a parent control.

  • The label does not have a parent control but is positioned next to another control, such as a text box or a check box. The Xpos of the control must be within 220 pixels of the end of the label (Xpos + Width). The Ypos of the control must be within 25 pixels of the label.

  • The label does not have a parent control but is the header of a group of indented controls, such as labels, text boxes, or check boxes. The Xpos of the controls must be indented at least 110 pixels and no more than 330 pixels from the Xpos of the label. The distance between the Ypos of the header and the first indented control or between two indented controls is no more than 660 pixels.

  • The label does not have a parent control but is used as instructional text. The instructional text is specified in the MoveElements.xml transformation input file.

The following sections describe how to troubleshoot different label scenarios.

To complete this procedure, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

Label Adjacent to a Control

If a label does not have a parent control other than the container control but is positioned near another control, then the label is transformed correctly. However, if the label is more than 220 pixels from the control, then the label is not connected to another control after it is transformed. The transformed label is a stand-alone control.

The following illustration shows a form with several text boxes and labels. The customer number (No.) label has the following properties:

  • ParentControl = Tab control (container control)

  • Xpos = 440

  • Width = 3300

The customer number text box has the following property:

  • Xpos = 3970

If a label does not have a parent control other than the container control, but the following equation is true, then it will be transformed correctly:

Xpos of control <= Xpos of label + width of label + 220

In this example, the Xpos of the control, which is 3970, is not less than or equal to the sum of the Xpos of the label, width of the label, and 220.

The following illustration shows the resulting page if you transform this form.

The customer number label is not transformed correctly. To resolve this issue, do one of the following:

  • Modify the label on the form so that it is positioned within the acceptable range of pixels from the control and then retransform the form.

  • Modify the label on the form so that its parent control is the text box instead of the tab control and then retransform the form.

To verify and modify labels on a form

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Form, select the form for which a label was not transformed correctly, and then click Design.

  3. In Form Designer, select the label, click the View menu, and then click Properties.

  4. Do one or both of the following:

    1. In the Label - Properties window, in the ParentControl field, enter the ID of the text box that the label identifies.

      Note Note

      The CaptionML value of the parent control is used as a label on the transformed page. If the label has a CaptionML value, then that value is transferred to the CaptionML value of the parent control during transformation and then used as a label on the transformed page.

    2. In the Label - Properties window, in the Xpos field, enter a position in pixels so that the label is within 220 pixels of the control. In the Ypos field, enter a position in pixels that is within 25 pixels of the control.

    The following illustration shows the transformed page with the label transformed correctly.

  5. To save and compile your form, close the form in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

Group Label

If a label does not have a parent control other than the container control but is the header of a group of indented controls, such as labels, text boxes, or check boxes, then the label is transformed correctly. However, if the controls are indented more than 330 pixels or less than 110 pixels from the label, then the label is not connected to another control after it is transformed. The transformed label is a stand-alone control. Additionally, if the Ypos of the header is more than 660 pixels from the first control in the group, then the label is not connected to another control after the label is transformed. The following illustration shows a form with several text boxes and labels. The Details label that is the header of a group has the following properties:

  • ParentControl = Tab control (container control)

  • Xpos = 440

The labels of the text boxes in the Details group each have the following property:

  • Xpos = 780

The Groups label that is the header of a group has the following properties:

  • ParentControl = Tab control (container control)

  • Ypos = 880

The labels of the text boxes under the Groups label have the following properties:

  • Customer Posting Group Ypos = 1550

  • Customer Price Group Ypos = 2200

  • Statistics Group Ypos = 2850

If a label does not have a parent control other than the container control but is the header of a group of labels and the following equations are true, then it will be transformed correctly:

Xpos of header label + 330 >= Xpos of indented group of labels >= Xpos of header label + 110

Ypos of header label + 660 >= Ypos of first indented group

In this example, the sum of the Xpos of the Details label, which is 440, and 330 is not greater than or equal to the Xpos of the indented group of labels. The sum of the Ypos of the Groups label, which is 880, and 660 is not greater than or equal to the Ypos of the first indented group.

The following illustration shows the resulting page if you transform this form.

The group header labels are not transformed correctly. To resolve this issue, modify the labels on the form so that they are positioned within the acceptable range of pixels from the group header label, and then retransform the form.

To verify and modify group labels on a form

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Form, select the form for which a label was not transformed correctly, and then click Design.

  3. If the group header label does not have a parent control but is the header of a group of indented controls, then verify that the label is positioned near the indented controls by performing the following steps:

    1. In Form Designer, select the label, click the View menu, and then click Properties.

    2. In the Label - Properties window, note the values in the Xpos and Ypos fields.

    3. In Form Designer, for each indented control, select the control, click the View menu, and then click Properties.

    4. In the Properties window of the control, verify that the value in the Xpos field is less than or equal to the Xpos of the group header label plus 330 and is greater than or equal to the Xpos of the group header label + 110.

    5. In the Properties window of the each control, verify that the difference between the values in the Ypos field of two labels is less than or equal to 660.

    The following illustration shows the transformed page with the label transformed correctly.

  4. To save and compile your form, close the form in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

Instructional Text

If a label does not have a parent control other than the container control but is marked as instructional text, then the label is transformed and placed at the top of the page. However, if it is not marked as instructional text in the transformation input file, then it is not placed at the top of the page after it is transformed. The following illustration shows a page with instructional text that was not marked as instructional text and is displayed at the bottom of the page instead of at the top.

To display the instructional text at the top of the page, modify the transformation input file by setting the Instructional TextML property on the label.

To verify and modify instructional text labels on a form

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, click Form, select the form for which a label was not transformed correctly, and then click Design.

  3. If the label does not have a parent control but is used as instructional text, verify that you have marked the label as instructional text in the transformation input file. For more information, see How to: Mark Labels on Dialogs as Instructions.

  4. To save and compile your form, close the form in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

    The following illustration shows the transformed page with the label that has been transformed correctly.

See Also

Tasks

How to: Retransform Forms


Troubleshooting: List Placement on Transformed Pages

Troubleshooting: List Placement on Transformed Pages

After you transform a form to a page. you may encounter problems if the form has multiple lists. The layout of those lists on the transformed page may be different from the layout of the lists on the form. You may want to change the layout on the page.

The following illustration shows a form with multiple lists.

In this example, the lists on the right of the form are subforms. If you transform this form, then the additional lists on the right of the form are transformed to FastTabs on the page. The following illustration shows the resulting page if you transform this form.

This transformed page may be suitable, or you may want to change the layout of the multiple lists on the page. You can change the layout in the following ways:

  • Specify input to the form transformation tool to change the subforms to FactBoxes.

  • Specify input to the form transformation tool to add promoted actions to display the subform information.

The following procedures describe how to make possible layout changes.

To complete this procedure, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

  • Transformation Input File (TIF) Editor. For more information, see How to: Install the Transformation Input File Editor.

To change a list to a FactBox

  1. Add the form and subforms to the TIF Editor. For more information, see How to: Get Forms in the Transformation Input File Editor.

  2. Select the main form in the TIF Editor and add FactBoxes to the transformation input for each subform. The type of the FactBoxes is Page. The PagePartID is the same as the ID of the subform. For more information, see How to: Add FactBoxes to Pages By Using Transformation Input.

  3. In the TIF Editor, specify that you want to delete each subform from the transformed page. For more information, see How to: Exclude Specific Controls from Transformation. In the Delete Page Elements window, specify the ID of the subform control on the form.

  4. Create the following transformation input files:

    • Transform Pages

    • Delete Page Elements

    For more information, see How to: Export Files from the Transformation Input File Editor.

  5. Export the forms to an .xml file and transform the forms to pages. For more information, see Transforming Forms.

    The following illustration shows the transformed page with subforms that have been transformed to FactBoxes.

To move a list to a promoted action

  1. Add the form and subforms to the TIF Editor. For more information, see How to: Get Forms in the Transformation Input File Editor.

  2. Select the main form in the TIF Editor and add promoted actions for each subform in the transformation input files. For more information, see How to: Promote Actions to the Action Pane By Using Transformation Input. In the Page Actions window, enter the subform ID in the RunObjectID field. In the RunObjectType field, select Page.

  3. In the TIF Editor, specify that you want to delete each subform from the transformed page. For more information, see How to: Exclude Specific Controls from Transformation. In the Delete Page Elements window, specify the ID of the subform control on the form.

  4. Create the following transformation input files:

    • Transform Pages

    • Delete Page Elements

    For more information, see How to: Export Files from the Transformation Input File Editor.

  5. Export the forms to an .xml file and transform the forms to pages. For more information, see Transforming Forms.

    The following illustration shows the transformed page with subforms that have been transformed to promoted actions.

See Also

Tasks

How to: Retransform Forms


Troubleshooting: Text Boxes Used as Labels on a Transformed Page

Troubleshooting: Text Boxes Used as Labels on a Transformed Page
See Also

After you transform a form to a page, you may encounter problems with text boxes that were used as labels on the form, because they may not be transformed correctly to labels on the page. This issue occurs when a text box on a form does not comply with the text box control mapping rules in the form transformation tool. For more information about built-in text box control rules, see the Text Box Control section of Control Mapping Rules.

Text boxes are transformed in the following cases:

  • Text box is a regular control. It is transformed to a field.

  • Text box is used for instructional text and has the Width property >= 6100. It is transformed to a field. In this case, the value of the SourceExpr property is transformed to the CaptionClass property of the transformed field. The result of the calculated CaptionClass property is displayed as the label.

  • Text box has the Focusable property set to No, has a value for the SourceExpr property, and is adjacent to another control. To be adjacent, the Xpos of the control must be between 55 and 165 pixels of the end of the text box (Xpos + Width). The Ypos of the control and the Ypos of the text box must be within 25 pixels of each other. In this case, the value of the SourceExpr property is transformed to the CaptionClass property of the field on the page. The result of the calculated CaptionClass property is displayed as the label.

    Note Note

    Using the CaptionClass property of a text box as the label instead of using a label causes the client to submit more requests to the server to calculate the CaptionClass value and therefore can affect performance.

The following procedure describes how to verify and redesign text boxes that are used as labels on the form so that they are transformed correctly.

To complete this procedure, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

Text Box Used as a Label

The following illustration shows a form that uses a text box as a label. In this example, the text box does not meet the Xpos requirements to be adjacent to another control.

The following illustration shows the resulting page if you transform this form.

The Overdue Amounts (LCY) label is not transformed correctly. To resolve this issue, move the text box or the adjacent control so that Xpos of the adjacent control is between 55 and 165 pixels of the end of the text box used as a label (Xpos + Width) and the Ypos of the control is within 25 pixels of the Ypos of the text box used as a label.

To verify that the text box label is adjacent to the control

  1. In the Classic client, on the Tools menu, click Object Designer.

  2. In Object Designer, select Form, select the form that you want to transform, and then click Design.

  3. If the following conditions are true for the text box, then the value of the SourceExpr property are transformed to the value of the CaptionClass property of the adjacent control. The value of the CaptionClass property is then used as a label on the page.

    • The text box does not have a parent control other than the container control.

    • The Focusable property is set to No.

    • The SourceExpr property has a value.

    • The text box is positioned adjacent to another control, such as an option button.

    Note Note

    The text box is considered adjacent to anther control if the Xpos of the adjacent control is between 55 and 165 pixels of the end of the text box used as a label (Xpos + Width) and the Ypos of the control is within 25 pixels of the Ypos of the text box used as a label.

    The following illustration shows the transformed page with the text box label transformed correctly.

  4. To save and compile your form, close the form in Form Designer. In the Save Changes window, confirm that the Compile check box is selected, and then click Yes.

See Also

Tasks

How to: Retransform Forms


Form Transformation Reference

Form Transformation Reference

The topics in this section are reference topics that list the following:

  • Mapping rules from forms to pages

  • Code transformation rules for removing unsupported triggers and methods

  • Redesigned forms for the RoleTailored client

See Also

Concepts

Form Property Mapping Rules
Control Property Mapping Rules
Control Mapping Rules
Method Mapping Rules
Trigger Mapping Rules
Code Rules
Redesigned Forms with Matrix-Like Layout
Redesigned Matrix Forms
Codeunit 9200 Matrix Management
Form Type to Page Type Mapping


Form Property Mapping Rules

Form Property Mapping Rules

The following table shows the mapping rules from Classic client form properties to RoleTailored client page properties.

The Mapping rule column in the table contains the following rules:

  • Transforms - The form property transforms to a page property.

  • Does not transform - The form property does not transform to a page property and is ignored by the transformation tool.

Form property | Mapping rule | Page property
ActiveControlOnOpen Property | Does not transform | Not applicable
AutoPosition Property | Does not transform | Not applicable
AutoSplitKey Property | Transforms | AutoSplitKey
BackColor Property | Does not transform | Not applicable
BorderStyle Property | Does not transform | Not applicable
CalcFields Property | Does not transform | Not applicable
Caption Property | Does not transform | Not applicable
CaptionBar Property | Does not transform | Not applicable
CaptionML Property | Transforms | CaptionML
DataCaptionExpr Property | Transforms | DataCaptionExpr
DataCaptionFields Property | Transforms | DataCaptionFields
DelayedInsert Property | Transforms | DelayedInsert
DeleteAllowed Property | Transforms | DeleteAllowed
Description Property | Transforms | Description
Editable Property | Transforms | Editable
Height Property | Does not transform | Not applicable
HorzGrid Property | Does not transform | Not applicable
ID Property | Transforms | ID
InsertAllowed Property | Transforms | InsertAllowed
LinksAllowed Property | Transforms | LinksAllowed
LogWidth Property | Does not transform | Not applicable
LogHeight Property | Does not transform | Not applicable
LookupMode Property | Does not transform | Not applicable
Minimizable Property | Does not transform | Not applicable
MinimizedOnOpen Property | Does not transform | Not applicable
Maximizable Property | Does not transform | Not applicable
MaximizedOnOpen Property | Does not transform | Not applicable
ModifyAllowed Property | Transforms | ModifyAllowed
MultipleNewLines Property | Transforms | MultipleNewLines
Name Property | Transforms | Name
Permissions Property | Transforms | Permissions
PopulateAllFields Property | Transforms | PopulateAllFields
SaveColumnWidths Property | Does not transform | Not applicable
SaveControlInfo Property | Does not transform | Not applicable
SavePosAndSize Property | Does not transform | Not applicable
SaveTableView Property | Does not transform | Not applicable
SaveValues Property | Transforms | SaveValues
Sizable Property | Does not transform | Not applicable
SourceTable Property | Transforms | SourceTable
SourceTablePlacement Property | Does not transform | Not applicable
SourceTableRecord Property | Does not transform | Not applicable
SourceTableTemporary Property | Transforms | SourceTableTemporary
SourceTableView Property | Transforms | SourceTableView
TableBoxID Property | Does not transform | Not applicable
TimerInterval Property | Does not transform | Not applicable
UpdateOnActivate Property | Transforms | RefreshOnActivate
VertGrid Property | Does not transform | Not applicable
Visible Property | Does not transform | Not applicable
XPos Property | Does not transform | Not applicable
YPos Property | Does not transform | Not applicable

See Also

Reference

Page Properties

Concepts

Creating and Maintaining Pages

Other Resources

Designing Forms


Control Property Mapping Rules

Control Property Mapping Rules

The following table shows the mapping rules from Classic client control properties to RoleTailored client control properties.

The Mapping rule column in the table contains the following rules:

  • Transforms - The form property transforms to a page property.

  • Does not transform - The form property does not transform to a page property and is ignored by the transformation tool.

Classic client control property | Mapping rule | RoleTailored client control property
AssistEdit Property | Transforms | AssistEdit
AutoCalcField Property | Does not transform | Not applicable
AutoEnter Property | Does not transform | Not applicable
AutoFormatExpr Property | Transforms | AutoFormatExpr
AutoFormatType Property | Transforms | AutoFormatType
AutoRepeat Property | Does not transform | Not applicable
BackColor Property | Does not transform | Not applicable
BackTransparent Property | Does not transform | Not applicable
Bitmap Property | Does not transform | Not applicable
BitmapList Property | Does not transform | Not applicable
BitmapPos Property | Does not transform | Not applicable
BlankNumbers Property | Transforms | BlankNumbers
BlankZero Property | Transforms | BlankZero
Border Property | Does not transform | Not applicable
BorderColor Property | Does not transform | Not applicable
BorderStyle Property | Does not transform | Not applicable
BorderWidth Property | Does not transform | Not applicable
Cancel Property | Does not transform | Not applicable
Caption Property | Does not transform | Not applicable
CaptionClass Property | Transforms | CaptionClass
CaptionML Property | Transforms | CaptionML
CharAllowed Property | Transforms | CharAllowed
ClearOnLookup Property | Does not transform | Not applicable
ClosingDates Property | Transforms | ClosingDates
DateFormula Property | Transforms | DateFormula
DecimalPlaces Property | Transforms | DecimalPlaces
Default Property | Does not transform | Not applicable
Description Property | Transforms | Description
Divisor Property | Does not transform | Not applicable
DrillDown Property | Transforms | DrillDown
DrillDownFormID Property | Transforms | DrillDownFormID
DropDown Property | Does not transform | Not applicable
Editable Property | Transforms | Editable (updated from a Boolean value to an expression that returns a Boolean value)
Ellipsis Property | Does not transform | Not applicable
Enabled Property | Transforms | Enabled (updated from a Boolean value to an expression that returns a Boolean value)
Focusable Property | Does not transform | Not applicable
FocusOnClick Property | Does not transform | Not applicable
FontBold Property | Transforms | Style and StyleExpr If FontBold is true and ForeColor is 255 (red), then Style is Unfavorable and StyleExpr is true. If FontBold is true and ForeColor is 65280 (green), then Style is Favorable and StyleExpr is true. If FontBold is true and ForeColor is not 255 or 65280, then Style is Strong and StyleExpr is true. Otherwise, Style is None and StyleExpr is false.
FontItalic Property | Does not transform | Not applicable
FontName Property | Does not transform | Not applicable
FontSize Property | Does not transform | Not applicable
FontStrikethru Property | Does not transform | Not applicable
FontUnderline Property | Does not transform | Not applicable
ForeColor Property | Transforms | Style and StyleExpr If FontBold is false and ForeColor is 255 (red), then Style is Attention and StyleExpr is true. If FontBold is true and ForeColor is 255 (red), then Style is Unfavorable and StyleExpr is true. If FontBold is true and ForeColor is 65280 (green), then Style is Favorable and StyleExpr is true. Otherwise, Style is None and StyleExpr is false.
Format Property | Does not transform | Not applicable
HeadingHeight Property | Does not transform | Not applicable
Height Property | Does not transform | Not applicable
HorzAlign Property | Does not transform | Not applicable
HorzGlue Property | Does not transform | Not applicable
ID Property | Transforms | ID
InColumn Property | Does not transform | Not applicable
InColumnHeading Property | Does not transform | Not applicable
InFrame Property | Does not transform | Not applicable
InlineEditing Property | Does not transform | Not applicable
InMatrix Property | Does not transform | Not applicable
InMatrixHeading Property | Does not transform | Not applicable
InPage Property | Does not transform | Not applicable
InvalidActionAppearance Property | Does not transform | Not applicable
LeaderDots Property | Does not transform | Not applicable
Lookup Property | Transforms | Lookup
LookupFormID Property | Transforms | LookupFormID
MatrixColumnWidth Property | Does not transform | Not applicable
MatrixSourceTable Property | Does not transform | Not applicable
MaxLength Property | Does not transform | Not applicable
MaxValue Property | Transforms | MaxValue
MenuItemType Property | Does not transform | Not applicable
MenuLevel Property | Does not transform | Not applicable
MinValue Property | Transforms | MinValue
MultiLine Property | Transforms | MultiLine
Name Property | Transforms | Name
NextControl Property | Does not transform | Not applicable
NotBlank Property | Transforms | NotBlank
Numeric Property | Transforms | Numeric
OptionCaption Property | Does not transform | Not applicable
OptionCaptionML Property | Transforms | OptionCaptionML
OptionString Property | Does not transform | Not applicable
OptionValue Property | Does not transform | Not applicable
Orientation (Indicator) Property | Does not transform | Not applicable
PadChar Property | Does not transform | Not applicable
PageNames Property | Does not transform | Not applicable
PageNamesML Property | Transforms | Tab names that are listed in the PageNames property on the form are transformed to FastTab captions on the page.
ParentControl Property | Does not transform | Not applicable
PasswordText Property | Transforms | ExtendedDataType=Masked
Percentage Property | Does not transform | Not applicable
PermanentAssist Property | Does not transform | Not applicable
PushAction Property | Does not transform | Not applicable
RowHeight Property | Does not transform | Not applicable
RunCommand Property | Does not transform | Not applicable
RunFormLink Property | Transforms | RunFormLink
RunFormLinkType Property | Does not transform | Not applicable
RunFormOnRec Property | Transforms | RunFormOnRec
RunFormView Property | Transforms | RunFormView
RunObject Property | Transforms | RunObject
ShapeStyle Property | Does not transform | Not applicable
ShortCutKey Property | Transforms | ShortCutKey
ShowCaption Property | Does not transform | Not applicable
SignDisplacement Property | Does not transform | Not applicable
SourceExpr Property | Transforms | SourceExpr
SubFormID Property | Transforms | SubFormID
SubFormLink Property | Transforms | SubFormLink
SubFormView Property | Transforms | SubFormView
TableRelation Property | Transforms | TableRelation
Title Property | Transforms | Title
ToolTip Property | Does not transform | Not applicable
ToolTipML Property | Transforms | ToolTipML
TopLineOnly Property | Does not transform | Not applicable
UpdateOnAction Property | Does not transform | Not applicable
ValidateTableRelation Property | Does not transform | Not applicable
ValuesAllowed Property | Transforms | ValuesAllowed
VertAlign Property | Does not transform | Not applicable
VertGlue Property | Does not transform | Not applicable
Visible Property | Transforms | Visible (updated from a Boolean value to an expression that returns a Boolean value)
Width Property | Does not transform | Not applicable
XPos Property | Does not transform | Not applicable
YPos Property | Does not transform | Not applicable

See Also

Reference

Page Properties

Concepts

Creating and Maintaining Pages

Other Resources

Designing Forms


Control Mapping Rules

Control Mapping Rules

The following tables show the mapping rules from Classic client form controls to RoleTailored client page controls.

Note Note

All actions are placed in action groups. Action groups have different subtypes that specify in which menu in the Command Bar the action will be displayed. For more information about action groups and subtypes, see How to: Add Actions to a Page.

Command Button Control
Command button control on Classic client form Mapping rule Page control

Application-specific command buttons (except Comment and Help)

Moved to the Actions menu in the command bar. Property Promoted=Yes.

Action

Comment and Help buttons

Does not transform

Not applicable

System command buttons:

  • OK/Cancel

  • Close

  • Yes/No

  • LookupOK

  • LookupCancel

  • Removed

  • If code is present, it is moved to the OnQueryClosePage trigger. The code is placed in an IF statement that corresponds to the return value from the system button.

Not applicable
Label Control
Label control on Classic client form Mapping rule Page Control

Label is a child to a parent control and label does not have a CaptionML value

The label is not transformed.

CaptionML of the parent control is used as a label

Label is a child to a parent control and label has a CaptionML value

CaptionML value of the label is transferred to the CaptionML of the parent control. The label is not transformed.

CaptionML of the parent control, which was transferred from the label, is used as a label.

Label is a stand-alone (parentless) control that is adjacent to another control (for example, a text box or a check box), and the other control has the following X and Y positions:

  • Xpos of control <= Xpos of the label + label width + 220 pixels

  • Ypos = Ypos of the label ±25

CaptionML value of the label is transformed to CaptionML of the adjacent control. The label is not transformed. The action is logged.

CaptionML of the adjacent control, which was transferred from the label, is used as a label.

Label is a stand-alone (parentless) control that is used as the header of a group of indented controls (labels, text boxes, or check boxes), and these indented controls have the following X and Y positions:

  • Xpos of control <= Xpos of the label + 330 pixels

  • Xpos of control >= Xpos of the label + 110 pixels

  • Ypos of control - Ypos of label >= 0

  • Distance between Ypos of two indented controls is a maximum of 660

CaptionML value of label is transformed as a CaptionML (header) for a group of controls.

The CaptionML property of the group contains the form's label CaptionML value.

Label is a stand-alone (parentless) control and is marked as InstructionalTextML

CaptionML of the label is transformed to InstructionalTextML property of its group. You must specify instructional text in the MoveElements.xml file for each group on the page.

InstructionalTextML is a property on a group.

Label is a stand-alone (parentless) control and is not marked as InstructionalTextML but still can be recognized as InstructionalTextML

CaptionML of the label is transformed to InstructionalTextML property of its group. The action is logged.

InstructionalTextML is a property on a group.

Label is a standalone (parentless) control that is not marked as InstructionalTextML

Transformed as a control with CaptionML but without SourceExpr.

Control without SourceExpr.

Label is a parent to other controls

Log as exception.

Not applicable
Menu Button Controls
Menu button control on Classic client form Mapping rule Page control

Menu buttons calling a form

  • Moved to the menu bar

  • Distributed between the Actions and Related Information menus based on the following distribution rules:

    • By default, all menu items are moved to the Related Information container

    • Transformation input file, MoveElements.xml, specifies that actions with the following CaptionML values are moved to the Actions menu: ENU=Posting, ENU=Issuing, ENU=Registering, ENU=Functions, ENU=Print

  • Placed in the same sorting order as displayed on the form

Action

Menu buttons calling the subform

Moved to subpage under the Actions menu.

Menu buttons are moved to the subpage in many cases but in others remain on the main page.

In some cases, menu buttons that call the subform are not moved to a subpage but are instead logged. The user must modify the form manually.

Action in the Actions menu.

Separator (MenuItemType)

Transformed to the new separator MenuType

SeparatorControl
Subform Controls
Subform control on Classic client form Mapping rule Page control

In documents

  • Transformed to a group

  • Placed second in a sorting order

ListPart

In other forms

  • Transformed to a group

  • Placed in the same sorting order as on the form, for example as a last control

ListPart
Text Box Control
Text box control on Classic client form Mapping rule Page control

Text box control

  • Transformed to a field

  • Placed in the same sorting order as displayed on the form

Field

Text box is a control with Focusable=No and SourceExpr=<value>. Text box is positioned adjacent to another control (for example, an OptionButton)

SourceExpr value is transformed to the CaptionClass property of the parent control. The text box is not transformed.

Not applicable

Text box is a control used for instructional text with width>=6100

Transformed to a control with a CaptionClass but without a SourceExpr

Field
Other Controls
Control on Classic client form Mapping rule Page control

Check Box (same as Text Box)

See Text Box Control table

Field

Frame

  • If placed on a tab, transformed to a group

  • If placed on a form directly, transformed to a FastTab

  • Placed in the same sorting order as displayed on the form

Group

Image

Does not transform

Not applicable

Indicator

Transformed into a progress bar on the page

Progress Indicator (=PowerBar)

Matrix Box

Logged as exception

Not applicable

Picture Box

Does not transform

Not applicable

Option Button (same as Text Box)

A group of radio buttons is transformed as a single control with an enumerated list of options.

RadioButton or DropDown depending on display target and number of options.

Shape

Does not transform

Not applicable

Tab

  • Transformed to a FastTab

  • Placed in the same sorting order as tabs

  • CaptionML=value transformed as a CaptionML (header) for the FastTab

Group

Table Box

Transformed

Repeater


Method Mapping Rules

Method Mapping Rules

To ensure that all code is compiled successfully, methods in the following table are removed using CodeRules input during transformation.

Note Note

Only code that exactly matches the code in the CodeRules.txt file is removed during transformation. For example, if the CodeRules.txt file contains a rule to remove !currForm!.EDITABLE := TRUE, then all instances of !currForm!.EDITABLE := TRUE will be removed. Instances of !currForm!.EDITABLE(TRUE) will not be removed.

Method | Type
[Action :=] FORM.RUNMODAL(Number [, Record] [, Field]) | Form Method
FORM.RUN(Number [, Record] [, Field]) | Form Method
[CurrXPos :=] f.XPOS([NewXPos]) | Form Method
[CurrYPos :=] f.YPOS([NewYPos]) | Form Method
[CurrWidth :=] f.WIDTH([NewWidth]) | Form Method
[CurrHeight :=] f.HEIGHT([NewHeight]) | Form Method
[CurrLogWidth :=] f.LOGWIDTH([NewLogWidth]) | Form Method
[CurrLogHeight :=] f.LOGHEIGHT([NewLogHeight]) | Form Method
[IsEditable :=] f.EDITABLE([SetEditable]) | Form Method
[IsVisible :=] f.VISIBLE([SetVisible]) | Form Method
[CurrCaption :=] f.CAPTION([NewCaption]) | Form Method
[CurrMinimized :=] f.MINIMIZEDONOPEN([NewMinimized]) | Form Method
[CurrMaximized :=] f.MAXIMIZEDONOPEN([NewMaximized]) | Form Method
[IsInLineEditing :=] INLINEEDITING([SetInLineEditing]) | Form Method
[CurrLookupMode :=] f.LOOKUPMODE([NewLookupMode]) | Form Method
[CurrLanguage :=] f.LANGUAGE([NewLanguage]) | Form Method
String := f.URL([UseNames]) | Form Method
String := f.OBJECTID([UseNames]) | Form Method
CurrForm.SAVERECORD | Form Method
CurrForm.UPDATE([SaveRecord/Default=True]) | Form Method
CurrForm.UPDATECONTROLS | Form Method
f.GETRECORD(Record) | Form Method
f.SETRECORD(Record) | Form Method
f.SETTABLEVIEW(Record) | Form Method
CurrForm.SETSELECTIONFILTER(Record) | Form Method
IsActive := f.ACTIVE | Form Method
[Ok :=] f.ACTIVATE | Form Method
f.CLOSE | Form Method
[Action :=] f.RUNMODAL | Form Method
f.RUN | Form Method
[CurrxPos :=] CurrForm.c.XPOS([NewxPos]) | Control Method
[CurryPos :=] CurrForm.c.YPOS([NewyPos]) | Control Method
[CurrWidth :=] CurrForm.c.WIDTH([NewWidth]) | Control Method
[CurrHeight :=] CurrForm.c.HEIGHT([NewHeight]) | Control Method
[IsVisible :=] CurrForm.c.VISIBLE([SetVisible]) | Control Method
[IsEditable :=] CurrForm.c.EDITABLE([SetEditable]) | Control Method
[IsEnabled :=] CurrForm.c.ENABLED([SetEnabled]) | Control Method
[CurrMaxDecimals :=] CurrForm.c.DECIMALPLACESMAX([NewMaxDecimals]) | Control Method
[CurrMinDecimals :=] CurrForm.c.DECIMALPLACESMIN([NewMinDecimals]) | Control Method
CurrForm.c.UPDATE | Control Method
CurrForm.c.ACTIVATE | Control Method
SubForm := CurrForm.c.FORM | Control Method
CurrForm.c.UPDATEINDENT(Indent) | Control Method
CurrForm.c.UPDATESELECTED(Selected) | Control Method
CurrForm.c.UPDATEEDITABLE(Editable) | Control Method
CurrForm.c.UPDATEFORECOLOR(ForeColor) | Control Method
CurrForm.c.UPDATEFONTBOLD(FontBold) | Control Method


Trigger Mapping Rules

Trigger Mapping Rules

The tables in this topic describe the transformation mapping rules for form and control triggers. The rules map triggers in the Classic client to triggers in the RoleTailored client.

Form Triggers

The following form triggers are transferred directly to page triggers:

  • OnAfterGetRecord Trigger

  • OnCloseForm Trigger

  • OnDeleteRecord Trigger

  • OnFindRecord Trigger

  • OnInit Trigger

  • OnModifyRecord Trigger

  • OnNewRecord Trigger

  • OnNextRecord Trigger

  • OnOpenForm Trigger

  • OnQueryCloseForm Trigger (transformed to OnQueryClosePage)

The following table shows form triggers that are not supported in the RoleTailored client and are transformed.

Form trigger Transformation rule

OnActivateForm Trigger

Code moved to local function OnActivateForm.

A call to this function is added to the OnOpenPage trigger.

OnAfterGetCurrRecord Trigger

Code moved to local function OnAfterGetCurrRecord in the following way.

CopyCode image Copy Code
OnAfterGetCurrRecord()
   xRec := Rec;
   // Code from form trigger

OnBeforePutRecord Trigger

Code moved to local function OnBeforePutRecord.

A call to this function is not added.

OnCreateHyperlink Trigger

Code moved to local function OnCreateHyperlink.

A call to this function is not added.

OnDeactivateForm Trigger

Code moved to local function OnDeactivateForm.

A call to this function is not added.

OnHyperlink Trigger

Code moved to local function OnHyperlink.

A call to this function is not added.

OnTimer Trigger

Code moved to local function OnTimer.

A call to this function is not added.

Control Triggers

This section describes the transformation mapping rules for the following control triggers:

  • Label triggers

  • Text box triggers

  • Check box triggers

  • Option button triggers

  • Subform and menu button triggers

  • Command button triggers

  • Menu item triggers

Label Triggers

The following table shows the transformation rules for label triggers.

Label trigger | Transformation rule
OnPush | Deleted

Text Box Triggers

The following table shows the transformation rules for text box triggers.

Text box trigger | Transformation rule
OnActivate | Code moved to local function <ControlSource>OnActivate. A call to this function is not added.
OnAfterInput | Code moved to local function <ControlSource>OnAfterInput. A call to this function is not added.
OnAfterValidate | Code moved to local function <ControlSource>OnAfterValidate. A call to this function is added to the OnValidate field trigger.
OnAssistEdit | Transformed directly to OnAssistEdit field trigger.
OnBeforeInput | Code moved to local function <ControlSource>OnBeforeInput. A call to this function is not added.
OnDeactivate | Code moved to local function <ControlSource>OnDeactivate. A call to this function is not added.
OnDrillDown | Transformed directly to OnDrillDown field trigger.
OnFormat | Code moved to local function <ControlSource>OnFormat. A call to this function is added to the OnAfterGetRecord page trigger.
OnInputChange | Code moved to local function <ControlSource>OnInputChange. A call to this function is not added.
OnLookup | Transformed directly to OnLookup field trigger.
OnValidate | Transformed directly to OnValidate field trigger.

Check Box Triggers

The following table shows the transformation rules for check box triggers.

Check box trigger | Transformation rule
OnActivate | Code moved to local function <ControlSource>OnActivate. A call to this function is not added.
OnAfterValidate | Code moved to local function <ControlSource>OnAfterValidate. A call to this function is added to the OnValidate field trigger.
OnDeactivate | Code moved to local function <ControlSource>OnDeactivate. A call to this function is not added.
OnPush | Code moved to local function <ControlSource>OnPush. A call to this function is added to the OnValidate field trigger.
OnValidate | Transformed directly to OnValidate field trigger.

Option Button Triggers

The following table shows the transformation rules for option button triggers.

Option button trigger | Transformation rule
OnActivate | Code moved to local function <ControlSource>OnActivate. A call to this function is not added.
OnAfterValidate | Code moved to local function <ControlSource>OnAfterValidate. A call to this function is added to the OnValidate field trigger.
OnDeactivate | Code moved to local function <ControlSource>OnDeactivate. A call to this function is not added.
OnPush | Code moved to local function <ControlSource>OnPush. A call to this function is added to the local function OnValidate.
OnValidate | Code moved to local function <ControlSource>OnValidate. A call to this function is added to the OnValidate field trigger with a preliminary check.

Subform and Menu Button Triggers

The following table shows the transformation rules for subform and menu button triggers.

Subform and menu button trigger | Transformation rule
OnActivate | Code moved to local function <ControlSource>OnActivate. A call to this function is not added.
OnDeactivate | Code moved to local function <ControlSource>OnDeactivate. A call to this function is not added.

Command Button Triggers

The following table shows the transformation rules for command button triggers.

Command button trigger Transformation rule

OnActivate

Code moved to local function <ControlSource>OnActivate.

A call to this function is not added.

OnDeactivate

Code moved to local function <ControlSource>OnDeactivate.

A call to this function is not added.

OnPush

Transformed to a page action. By default, action is moved to the Related Information menu. The Promoted property is true.

For specific captions, additional properties may be set. For more information, see the MoveElements.xml file.

OnValidate

Code moved to local function <ControlSource>OnValidate.

A call to this function is added to the OnValidate field trigger with a preliminary check.

The following table shows the transformation rules for specific command buttons.

Command button Transformation rule

Command button with PushAction=FormHelp

Not supported by the page object. All triggers are deleted.

Command button with one of the following:

  • PushAction=OK

  • PushAction=Cancel

  • PushAction=LookupOK

  • PushAction=LookupCancel

  • PushAction=Yes

  • PushAction=No

  • PushAction=Close

OnPush trigger code moved to OnQueryClosePage trigger and modified. New local functions are created in the OnQueryClosePage trigger and called by using the following code.

CopyCode image Copy Code
IF CloseAction = Action::LookupCancel THEN
    LookupCancelOnPush;

IF CloseAction = Action::LookupOK THEN
    LookupOKOnPush;

IF CloseAction IN [Action::Cancel,Action::LookupCancel] THEN
    CancelOnPush;

IF CloseAction IN [Action::OK,Action::LookupOK] THEN
    OKOnPush;

IF CloseAction = Action::Close THEN
    CloseOnPush;

IF CloseAction = Action::No THEN
    NoOnPush;

IF CloseAction = Action::Yes THEN
    YesOnPush;

Menu Item Triggers

The following table shows the transformation rules for menu item triggers.

Menu item trigger | Transformation rule
OnPush | Transformed to a page action. By default, action is moved to the Related Information menu. For specific captions, properties may be set. For more information, see the MoveElements.xml file.


Code Rules

Code Rules

The following tables show how code rules are used to remove unsupported triggers and methods. Code rules are written using syntax similar to regular expressions. A code rule uses one or more special words to match code on the form.

The following special words are used as tags to find and replace expressions, to create variables, and to move code and properties:

  • <find>

  • <replace>

  • <atTrigger>

  • <comment>

  • <declareVariable>

  • <declareVariableType>

  • <moveToProperty>

  • <moveValueToProperty>

  • <movePropertyToControlName>

  • <moveCodeToTrigger>

  • <moveToTrigger>

The following special words are used as placeholders for variables:

  • !var!

  • !var<int>!

  • !declaredVariable!

  • !currForm!

The following examples illustrate how code rules work and can be written. The first examples show simple find and replace rules. The next examples build on the find and replace rule.

<find> and <replace>

Use the <find> and <replace> special words to find specific code and replace it. If you omit the <replace> instruction in the code transformation rule, then the found code is deleted but not replaced with any code.

Code transformation rule Code before transformation Code after transformation
CopyCode image Copy Code
<find>
x := y;
CopyCode image Copy Code
MESSAGE('Hello');
x := y;
MESSAGE('World');
CopyCode image Copy Code
MESSAGE('Hello');
MESSAGE('World');
CopyCode image Copy Code
<find>
x := y;
<replace>
y := z;
CopyCode image Copy Code
MESSAGE('Hello');
x := y;
MESSAGE('World');
CopyCode image Copy Code
MESSAGE('Hello');
y := z;
MESSAGE('World');
CopyCode image Copy Code
<find>
x := TRUE;
<replace>
;
<find>
y := x;
<replace>
x := TRUE;
<find>
y := x;
<replace>
x := FALSE;
CopyCode image Copy Code
MESSAGE('Hello');
y := x;
MESSAGE('World');
Note Note

Rules are evaluated from top to bottom. Rules are run again if a match is found.

CopyCode image Copy Code
MESSAGE('Hello');
;
MESSAGE('World');

<atTrigger>

Use the <atTrigger> special word to specify that you want to find and replace code only if it is in the specified trigger.

Code transformation rule Code before transformation Code after transformation
CopyCode image Copy Code
<find>
x := y;
<atTrigger>
OnOpenForm
CopyCode image Copy Code
OnInit=BEGIN
  MESSAGE('Hello');
  x := y;
  MESSAGE('World');
END;

OnOpenForm=BEGIN
  MESSAGE('Hello');
  x := y;
  MESSAGE('World');
END;
CopyCode image Copy Code
OnInitPage=BEGIN
  MESSAGE('Hello');
  x := y;
  MESSAGE('World');
END;

OnOpenPage=BEGIN
  MESSAGE('Hello');
  MESSAGE('World');
END;

<comment>

Use the <comment> special word to add comments to the CodeRules.txt file. The comment is ignored in the code transformation.

Code transformation rule Code before transformation Code after transformation
CopyCode image Copy Code
<find>
x := z;
<comment>
Hello world
CopyCode image Copy Code
x := z;
MESSAGE('Hello World');
CopyCode image Copy Code
MESSAGE('Hello World');

!var! and !var<int>!

Use the !var! special word to specify a variable in the code. A !var! in a code rule matches any variable. You can specify different variables by appending an integer to !var!, such as !var1! or !var2!.

Code transformation rule Code before transformation Code after transformation
CopyCode image Copy Code
<find>
y := !var!
<replace>
y := TRUE;
CopyCode image Copy Code
MESSAGE('Hello');
y := x;
x := z;
MESSAGE('World');
CopyCode image Copy Code
MESSAGE('Hello');
y := TRUE;
x := z;
MESSAGE('World');
CopyCode image Copy Code
<find>
!var1! := !var2!
<replace>
!var2! := !var1!
CopyCode image Copy Code
MESSAGE('Hello');
y := x;
x := z;
MESSAGE('World;);
CopyCode image Copy Code
MESSAGE('Hello');
x := y;
z := x;
MESSAGE('World');

<declareVariable>, <declareVariableType>, and !declaredVariable!

Use the <declareVariable> special word to specify that the transformed code must declare a new variable. The expression after the <declareVariable> special word is the name of the new variable. Use the <declareVariableType> special word to specify the data type of the new variable that is declared. Use the !declaredVariable! special word to specify that you want to use the new variable that you declared.

Code transformation rule Code before transformation Code after transformation
CopyCode image Copy Code
<find>
!currForm!.!var1!.HEIGHT(!var2!)
<replace>
!currForm!.!var1!.HEIGHT := !var2!

<find>
CurrForm.!var1!.HEIGHT;
<declareVariable>
!var1!Height
<declareVariableType>
Integer
<replace>
!declaredVariable!;
CopyCode image Copy Code
OnRun=BEGIN
…
  MESSAGE('Hello');
  CurrForm.x.HEIGHT(NewHeight);
  MESSAGE('World');
END;
CopyCode image Copy Code
VAR
  xHeight : Integer;
OnRun=BEGIN
…
  MESSAGE('Hello');
  xHeight := NewHeight;
  MESSAGE('World');
END;

!currForm!

Use the !currForm! special word to specify either the CurrForm or CurrReport system-defined variable.

Code transformation rule Code before transformation Code after transformation
CopyCode image Copy Code
<find>
!currForm!.EDITABLE := TRUE
<replace>
;
CopyCode image Copy Code
MESSAGE('Hello')
CurrForm.EDITABLE := TRUE;
MESSAGE('World');
CopyCode image Copy Code
MESSAAGE('Hello');
;
MESSAGE('World');
CopyCode image Copy Code
<find>
!currForm!.EDITABLE := TRUE
<replace>
;
CopyCode image Copy Code
MESSAGE('Hello')
CurrReport.EDITABLE := TRUE;
MESSAGE('World');
CopyCode image Copy Code
MESSAAGE('Hello');
;
MESSAGE('World');

<moveToProperty>, <moveValueToProperty>, and <movePropertyToControlName>

Use the <moveToProperty> and the <moveValueToProperty> special words to move a value to the specified property. Use the <movePropertyToControlName> special word to move this property to the specified control.

Code transformation rule Code before transformation Code after transformation
CopyCode image Copy Code
<find>
Text := '';
<declareVariable>
!control!HideValue
<declareVariableType>
Boolean INDATASET
<replace>
!declaredVariable! := TRUE;
<atTrigger>
OnFormat
<moveToProperty>
HideValue
<moveValueToProperty>
!declaredVariable!
<movePropertyToControlName>
!control!
CopyCode image Copy Code
SourceExpr := x;
OnFormat=BEGIN
  MESSAGE('Hello');
  Text := '';
  MESSAGE('World');
END;
Note Note

Assume that the preceding code is on a control. In this example, SourceExpr = x. The rule functions in the same way if the code is in a control with the Name property = x, or ID = x.
CopyCode image Copy Code
VAR
  xHideValue : Boolean INDATASET;
SourceExpr = x;
HideValue = xHideValue;
OnFormat=BEGIN
  MESSAGE('Hello');
  xHideValue := TRUE;
  MESSAGE('World');
END;

<moveCodeToTrigger> and <moveToTrigger>

Use the <moveCodeToTrigger> special word to specify the code that you want to move to a trigger. Use the <moveToTrigger> special word to specify the trigger to which you want to move the code.

Code transformation rule Code before transformation Code after transformation
CopyCode image Copy Code
<find>
y := x;
<atTrigger>
OnDeactivateForm
<replace>
;
<moveToTrigger>
OnCloseForm
<moveCodeToTrigger>
y := x;
CopyCode image Copy Code
OnDeactivateForm=BEGIN
  MESSAGE('Hello');
  y := x;
  MESSAGE('World');
END;
OnInit=BEGIN
  MESSAGE('Hello');
  y := x;
  MESSAGE('World');
END;
CopyCode image Copy Code
OnClosePage=BEGIN
  y := x;
END;
OnInit=BEGIN
  MESSAGE('Hello');
  y := x;
  MESSAGE('World');
END;


Redesigned Forms with Matrix-Like Layout

Redesigned Forms with Matrix-Like Layout

The following table lists forms in the Microsoft Dynamics NAV Classic client with a matrix-like layout that have been redesigned. You can use these forms as examples when redesigning your own forms that have a matrix-like layout, before you transform your own forms. For more information about redesigning forms with matrix-like layout, see How to: Redesign Forms with Matrix-Like Layout of Controls.

Form ID | Form name
151 | Customer Statistics
152 | Vendor Statistics
223 | Resource Statistics
230 | Res. Gr. Statistics
302 | Customer Entry Statistics
303 | Vendor Entry Statistics
304 | Item Entry Statistics
375 | Bank Account Statistics
1024 | Job Task Statistics
1025 | Job Statistics
5602 | Fixed Asset Statistics
5603 | Main Asset Statistics
5914 | Service Order Statistics
5982 | Service Item Statistics
6030 | Service Statistics
6059 | Contract Statistics
99000756 | Work Center Statistics
99000762 | Machine Center Statistics
99000816 | Production Order Statistics


Redesigned Matrix Forms

Redesigned Matrix Forms

The following table shows matrix forms that have been redesigned in the Microsoft Dynamics NAV 2009 SP1 Classic client into a single redesigned form with a subform. Use these forms as examples when redesigning your own matrix forms. For more information about redesigning matrix forms, see Walkthrough: Redesigning the Acc. Schedule Overview Form and How to: Redesign Matrix Forms.

Matrix Forms in Microsoft Dynamics NAV 2009 SP1
Original form ID | Original form name | Redesigned form ID in Microsoft Dynamics NAV 2009 SP1
113 | Budget | 9202 and 9203
538 | Dimension Combinations | 9250 and 9251
539 | Dimension Value Combinations | 9252 and 9253
7138 | Purchase Budget Overview | 9218 and 9219
7139 | Sales Budget Overview | 9238 and 9239
213 | Resource Capacity | 9236 and 9237
214 | Res. Group Capacity | 9242 and 9243
99000919 | Production Forecast | 9244 and 9245

The following tables show matrix forms that have been redesigned in the Microsoft Dynamics NAV 2009 Classic client into two redesigned forms. One is the request form on which you set filters and options, and one is the list form that displays the data. We recommend that you do not redesign your forms in this way but instead redesign them into one a single form. You can redesign your forms into a single form if you are running either Microsoft Dynamics NAV 2009 or Microsoft Dynamics NAV 2009 SP1.

Analysis-Only Matrix Forms
Original form ID | Original form name | Redesigned form ID
221 | Resource Allocate per Job | 9210 and 9211
228 | Res. Gr. Allocated per Job | 9212 and 9213
408 | G/L Balance by Dimension | 9232 and 9233
490 | Acc. Schedule Overview | 9234 and 9235
491 | Items by Location | 9230 and 9231
554 | Analysis by Dimensions | 9248 and 9249
563 | G/L Entries Dimension Overview | 9240 and 9241
5099 | To-dos | 9254 and 9255
5131 | Opportunities | 9256 and 9257
5225 | Absence Overview by Periods | 9246 and 9247
5226 | Empl. Absences by Categories | 9268
5227 | Empl. Absences by Cat. Matrix | 9269
5230 | Qualification for Overview | 9270 and 9271
5231 | Absence Overview by Categories | 9272
5232 | Absence Over. By Cat. Matrix | 9273
5622 | Total Value Insured per FA | 9274 and 9275
5662 | FA Posting Types Overview | 9276 and 9277
5827 | Item Statistics | 9222 and 9223
6008 | Res. Alloc. Per Service Order | 9214 and 9215
6009 | Res. Gr. Alloc. Per Serv Order | 9216 and 9217
7117 | Sales Analysis Report | 9206 and 9207
7118 | Purchase Analysis Report | 9204 and 9205
7119 | Inventory Analysis Report | 9200 and 9201
7157 | Purch. Analysis by Dimensions | 9224 and 9225
7158 | Sales Analysis by Dimensions | 9226 and 9227
7159 | Invt. Analysis by Dimensions | 9208 and 9209
99000812 | Prod. BOM Matrix per Version | 9286 and 9287
Noneditable Matrix Forms, Editable Drill-Down
Original form ID | Original form name | Redesigned form ID
5228 | Misc. Articles Overview | 9280 and 9281
5229 | Confidential Info. Overview | 9282 and 9283
5747 | Transfer Routes | 9284 and 9285
6004 | Res. Availability (Service) | 9228 and 9229
6010 | Res. Gr. Availability (Service) | 9220 and 9221
6066 | Contract Gain/Loss (Groups) | 9258 and 9259
6067 | Contract Gain/Loss (Customers) | 9260 and 9261
6068 | Contract Gain/Loss (Reasons) | 9262 and 9263
6069 | Contract Gain/Loss (Resp. Ctr) | 9264 and 9265
6071 | Contract Gain/Loss (Contracts) | 9266 and 9267
99000769 | Work Center Calendar | 9292 and 9293
99000770 | Machine Center Calendar | 9292 and 9292
99000771 | Work Ctr. Group Calendar | 9294 and 9295
Editable Matrix Forms, Noneditable Drill-Down
Original form ID | Original form name | Redesigned form ID
213 | Resource Capacity | 9236 and 9237
214 | Res. Group Capacity | 9242 and 9243
99000919 | Production Forecast | 9244 and 9245
Editable Matrix Forms, Editable Drill-Down
Original form ID | Original form name | Redesigned form ID
113 | Budget | 9202 and 9203
538 | Dimension Combinations | 9250 and 9251
539 | Dimension Value Combinations | 9252 and 9253
5845 | Inventory - G/L Reconciliation | 9296 and 9297
7138 | Purchase Budget Overview | 9218 and 9219
7139 | Sales Budget Overview | 9238 and 9239

See Also

Tasks

How to: Redesign Matrix Forms
Walkthrough: Redesigning the Acc. Schedule Overview Form


Codeunit 9200 Matrix Management

Codeunit 9200 Matrix Management

The following tables show the input and output parameters for two matrix management functions in codeunit 9200, Matrix Management, in the standard application. Codeunit 9200 contains functions to manage the behavior of the new matrix forms after you have redesigned them so that they can be transformed. For more information about how to redesign matrix forms, see How to: Redesign Matrix Forms.

Function GenerateMatrixData

Var Input Output Name Date type Description

X

RedRef

RecordRef

The matrix record. You can filter as appropriate.

X

SetWanted

Option

Defines set of records that you want. The following options are available:

  • Initial

  • Previous

  • Same

  • Next

X

MaximumSetLength

Integer

The maximum number of records allowed in the set. Normally 32.

X

CaptionFieldNo

Integer

The field number of the field in the RecRef that is used as the caption.

X

X

X

PKFirstRecInCurrSet

Text

The primary key of the first record in the current set.

X

X

CaptionSet

Text

An array that contains the captions for the matrix.

X

X

CaptionRange

Text

The range of the specified CaptionSet.

X

X

CurrSetLength

Integer

The number of records in the current set.

Function GeneratePeriodMatrixData

The GeneratePeriodMatrixData function works in the same way as the GenerateMatrixData function except that it also does the following:

  • Generates an array of the matrix records in the set.

  • Generates more user-friendly captions (such as quarter/year instead of quarter).

  • Performs the typical date record filtering, such as when the period is an accounting period.

Var Input Output Name Date type Description

X

SetWanted

Option

The set of records that you want. The following options are available:

  • Initial

  • Previous

  • Same

  • Next

X

MaximumSetLength

Integer

The maximum number of records allowed in the set. Normally 32.

X

UseNameForCaption

Boolean

Specifies whether the Period Name field of the date record is used for captions. We recommend that you set this to No so that a user-friendly caption will be generated.

X

PeriodType

Option

The following options are available:

  • Day

  • Week

  • Month

  • Quarter

  • Year

  • Accounting Period

X

DateFilter

Text

The date filter.

X

X

X

PKFirstRedInCurrSet

Text

The primary key of the first record in the current set.

X

X

CaptionSet

Text

An array that contains the captions for the matrix.

X

X

CaptionRange

Text

The range of the specified CaptionSet.

X

X

CurrSetLength

Integer

The number of records in the current set.

X

X

PeriodRecords

Record Date

An array of the period records in the set.


Form Type to Page Type Mapping

Form Type to Page Type Mapping

The following table shows the forms types in the Classic client, a description of the form type, and the default page type to which each form will be transformed.

Form type Description PageType (default)

Advanced Confirmation

Card form that poses a question to the user, has no input fields, and requires that the user select Yes or No. In most cases, this form does not have a Source Table property defined and is based on variables in the form.

ConfirmationDialog

Bar Chart

Form that displays a bar chart; not available in the RoleTailored client.

Card

Card

Form with only TabControl and a source table.

Card

Chart of Accounts

Form with indented list in TableBox.

List

Document

Main or header form with TabControl and a frame that holds a subform.

Document

FixedLayout

Form with FixedLayout controls

Card

Homepage

Homepage (RoleTailored client form type).

PartPage

FactBox

InfoPart (RoleTailored client form type).

SimplePart

InfoPartLIst

List InfoPart (RoleTailored client form type).

ListPart

Journal

Form that is based on a template, batch, or name structure and has a control for selecting a template, batch, or name. Often includes forms named Worksheets.

Worksheet

List

Form with a TableBox control only.

List

Matrix

Form with a MatrixBox control or the header form for matrixes that have a header or subform structure.

Card

Matrix Subform

Form which is a subform with a MatrixBox.

List

Navigate

Form with only one instance.

NavigatePage

Property Sheet

Form with the same layout as the Document form type, but is not in itself a business entity that would be sent through a process or create transactions.

ListPlus

Stack

Also called Activities (RoleTailored client form type).

SimplePart

Standard Dialog

Card form which has no question or requires that the user select Yes or No to perform the command that the user selected. In most cases, this form does not have a Source Table property.

Card

Subform List

Form which is a subform with a list

ListPart

Subform Worksheet

Form which is a subform with a worksheet

ListPart

Trendscape

Form with the Period buttons and a subform that is a TableBox (not a MatrixBox).

List

Trendscape Subform

Form that is a subform to a trendscape form.

ListPart

Wizard

Form with a wizard structure or the header form for a wizard that has a header or subform structure.

NavigatePage

Wizard Subform

Form which is a subform with a wizard

ListPart

Worksheet

Form with the following characteristics:

  • A single form, not a main and a subform

  • Has a TableBox as a primary ControlContainer

  • No template, batch, or name structure

  • Has at least one other control that is not a command button or MenuItem that is not part of the list

Worksheet


Working with Web Services

Working with Web Services

The following sections provide an overview of the available documentation about Web services in Microsoft Dynamics NAV 2009.

With the introduction of Microsoft Dynamics NAV Server, Microsoft Dynamics NAV supports Web services, which makes integration with other systems easier. Microsoft Dynamics NAV supports exposing pages and codeunits as Web services.

Note Note

The content in this the following topics has been updated to provide information that only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Getting Started with Web Services

Find out how Web services are implemented in Microsoft Dynamics NAV.

To | See
Learn about Web services functionality in Microsoft Dynamics NAV. | Microsoft Dynamics NAV Web Services
Learn about what Web services can be used for. | Examples of Web Services
Learn about enhancements and improvements to Web services functionality in Microsoft Dynamics NAV 2009 SP1. | Web Services Changes for Microsoft Dynamics NAV 2009 SP1

Creating Web Services

When creating Web services, you must consider whether to create a new Web service or use an existing page or codeunit.

To | See
Learn how to write code that provides a list of existing companies on a Microsoft Dynamics NAV installation. | How to: Use SystemService to Find Companies
Understand what to be aware of when working with exceptions and Web services. | Handling UI Interaction When Working with Web Services
Write a simple codeunit and expose it as a Web service. | Walkthrough: Creating and Consuming a Codeunit Web Service
Register an existing page as a Web service and call it from code. | Walkthrough: Registering and Consuming a Page Web Service
Read about signature and code examples for the basic page operations that are exposed on a page Web service by default. | Basic Page Operations

Exposing Web Services

To enable other applications to use the Web service that you created, expose the Web service from Microsoft Dynamics NAV.

To | See
Expose a codeunit or a page as a Web service. | How to: Register a Web Service
Expose an extension to a page. | Walkthrough: Creating a Web Service using Extension Codeunits

See Also

Tasks

How to: Register a Web Service
Walkthrough: Creating and Consuming a Codeunit Web Service


Microsoft Dynamics NAV Web Services

Microsoft Dynamics NAV Web Services

Microsoft Dynamics NAV 2009 provides Web services, which makes it easy for other systems to integrate with Microsoft Dynamics NAV.

Web service integration with Microsoft Dynamics NAV is supported through Web service–enabled pages and codeunits. With proper authentication and authorization, external systems can read and write data on pages and call codeunits as XML Web services using SOAP over HTTP and having their interfaces exposed in a WSDL. When pages and codeunits are published as Web services from Microsoft Dynamics NAV, they are immediately available for Web service requests over the network.

Different Types of Web Services

Microsoft Dynamics NAV supports exposing pages and codeunits as Web services. Pages and codeunits can be combined to offer more functionality on the page Web service.

Page Web Services

When a page is exposed as a Web service, a default set of operations is exposed to developers so that they can manage common record handling operations such as Create, Read, Update, and Delete. Page-based Web services offer built-in optimistic concurrency management. Each operation call in a page-based Web service is managed as a single transaction.

You can also use extension codeunits to extend the default set of operations that are available on a page. Adding an extension codeunit to a page is useful if you want to perform operations other than the standard Create, Read, Update, and Delete operations.

The benefit of adding an extension codeunit to a page is that you can make the Web service more complete by adding operations that are logical to that service. Those operations can use the same object identification principle as the basic page operations.

Codeunit Web Services

Codeunit Web services provide you with the most control and flexibility. When a codeunit is exposed as a Web service, no default set of operations is exposed. You can decide which operations are available on a codeunit.

The Microsoft Dynamics NAV Web services service is stateless and therefore does not preserve the values of the global variables between calls.

Virtual Tables

Virtual tables cannot be edited through Web services even if they are editable in Microsoft Dynamics NAV. Because each Web service operation invocation starts a new session and virtual tables are bound to that session, they can be used within the Web service operation, but they cannot be used across Web service operation invocations. Virtual tables are deleted when each Web service operation concludes.

URLs

Web service users can discover services from a server by pointing a browser or a tool such as the Web Services Discovery Tool at the computer running Microsoft Dynamics NAV Server and getting a list of available services. The general URL consists of the following elements:

  • http://<Server>:<WebServicePort>/<ServerInstance>/WS/<CompanyName>/services

The URL for accessing a specific page consists of the following elements:

  • http://<Server>:<WebServicePort>/<ServerInstance>/WS/<CompanyName>/Page/<ServiceName>

The URL for accessing a specific codeunit has the following elements:

  • http://<Server>:<WebServicePort>/<ServerInstance>/WS/<CompanyName>/Codeunit/<ServiceName>

Note Note

CompanyName, Page, Codeunit, and ServiceName are all case-sensitive.

The following table describes the elements of the URL.

URL element Description

Server

The name of the computer running the Microsoft Dynamics NAV Business Web Services service.

WebServicePort

The TCP port number used for the Web service. This is configured during service installation and is located in the CustomSettings.config file on the computer.

When exposing a Web service, you must open the port for other consumers of your Web service to access it. Have your system administrator add the port through Windows Firewall on the computer running Microsoft Dynamics NAV Server. The default port is set to 7047.

ServerInstance

A name that identifies the instance of Microsoft Dynamics NAV Server. The default value is DynamicsNAV.

This matches the value of the ServerInstance parameter in CustomSettings.config, the Microsoft Dynamics NAV Server configuration file. See Configuring Microsoft Dynamics NAV Server.

CompanyName

The name of the company. CompanyName is optional when accessing the WSDL or calling the SystemService Web service. The company name must be included in the URL used for all other Web service calls.

Note Note

Special characters in the company name must be URL encoded. For example, spaces in company names must be replaced by %20, so you would encode the company name "Microsoft France S.A." as:

Microsoft%20France%20S.A.

Characters that are not part of the installed language should also be replaced. For example, in a US-English locale, the company name "CRONUS ÆØÅ Company" should be encoded as:

CRONUS%20%C3%86%C3%98%C3%85%20Company

ServiceName

The service name for the exposed page or codeunit.
Note Note

A URL ending with "/" is not valid for a Microsoft Dynamics NAV Web service.

See Also

Tasks

How to: Register a Web Service
How to: Use SystemService to Find Companies

Concepts

Basic Page Operations
Web Services Programming Tips


Examples of Web Services

Examples of Web Services

With Microsoft Dynamics NAV Server, Microsoft Dynamics NAV 2009 supports Web services, which makes it easy for other system to integrate with Microsoft Dynamics NAV. Web service integration with Microsoft Dynamics NAV is facilitated through Web service–enabled pages and codeunits.

Examples

Web services support communication across platforms and programming languages.

Solutions that need to execute business logic or read data from Microsoft Dynamics NAV are candidates for Web service implementation. These can also be solutions that write data to Microsoft Dynamics NAV and validate the data using existing business logic.

Consider using Microsoft Dynamics NAV Web services to:

  • Validate or enter customer information.

  • Enter sales orders.

  • Query items on stock (delivery dates, discounts, prices, and so on).

  • Create purchase orders.

  • Initiate various Microsoft Dynamics NAV operations.

  • Execute any kind of business logic that is more easily developed and managed in Microsoft Dynamics NAV.

Security note Security Note

When developing Web service applications, never trust data that comes from the outside your company. You must always validate your data.

See Also

Tasks

How to: Register a Web Service
Walkthrough: Creating and Consuming a Codeunit Web Service
Walkthrough: Registering and Consuming a Page Web Service

Concepts

Microsoft Dynamics NAV Web Services


Web Services Changes for Microsoft Dynamics NAV 2009 SP1

Web Services Changes for Microsoft Dynamics NAV 2009 SP1

The following enhancements and improvements to Web services functionality in Microsoft Dynamics NAV 2009 have been included for the SP1 release:

  • Standard encoding for company name has been updated

  • Schema changes have been made in ReadMultiple and UpdateMultiple

  • Updating records in page-based Web services only updates the fields that you actually changed

  • Creatong and updating sales orders through a page-based Web service has changed

  • Web services do not change the user's default company

  • BLOB fields in page-based Web services are ignored

  • Codeunits ignore operations with unsupported parameters

  • Connections from either PHP or Java are now supported

Standard encoding for company name has been updated

Microsoft Dynamics NAV 2009 SP1 uses a standard encoding algorithm to represent special characters in company names as part of a URL. For example, "CRONUS USA, Inc." is displayed as "CRONUS%20USA%2C%20Inc."

Company name | Encoded version
CRONUS USA, Inc. | CRONUS%20USA%2C%20Inc.
CRONUS ÆØÅ Company | CRONUS%20%C3%86%C3%98%C3%85%20Company

You do not need to use encoding when typing a company name in a browser's Address bar or when typing a Web reference in Visual Studio. You can type the company name with spaces and special characters, or you can type the company name with encoding. Company names are always displayed with special characters when you view URLs.

This change affects the return values for the Companies function in the SystemService service, which returns unencoded company names in clear text. You can no longer use the output from the Companies function to build your URL. You must provide the encoded version of the company name. The advantage is that company names are now available in clear text (for example to be used in UIs). Always encode clear text company names if you are using them as part of a URL.

The new encoding is not destructive: you can encode and decode the company name and always get the same result. Another advantage is that company names can now be used to build URLs to start the RoleTailored client.

There is no backward compatibility with the pre-SP1 version of Microsoft Dynamics NAV 2009, so attempts to access Web services with a URL from that version will fail. To fix this problem, change the company name encoding.

Schema changes have been made in ReadMultiple and UpdateMultiple

Microsoft Office InfoPath could not modify multiple records using Microsoft Dynamics NAV page-based Web services because of a schema incompatibility. In Microsoft Dynamics NAV 2009 SP1, the schema for these operations has been updated. If you are using proxy-based Web services with Add Service Reference in Visual Studio 2008, or Add Web Reference in Visual Studio 2005, then you should update the reference. If you are using XML Web services, then you may need to modify the code that is used to parse the XML.

Updating records in page-based Web services only updates the fields that you actually changed

You can use Visual Studio to create a reference to a Web service. For example, you can get strongly typed access to customers and sales orders through pages.

Visual Studio autogenerates a <fieldname>Specified Boolean property for all nonstring fields that are received from Microsoft Dynamics NAV. In the pre-SP1 version of Microsoft Dynamics NAV 2009, a Web service would update all fields where <fieldname>Specified was true or where a string was not NULL. A NULL string value does not mean to clear the field. Instead, it means to not update the field. If you want to clear a field, then you set the value to String.Empty (“”).

In some cases, this implementation caused problems. For example, when you read a customer record to change the name, it was returned from the Get function with all <fieldname>Specified properties set to true and all string fields having content. To change the name of a customer, you must write to the Name field. Because the Searchname field is included in the data that is sent to a Web service, it would be updated, and the Name and Searchname fields could be out of sync. To update this field, you would need to set all other fields to NULL or <fieldname>Specified to false.

In Microsoft Dynamics NAV 2009 SP1, Visual Studio still uses <fieldname>Specified and string field <> NULL to determine what is sent, but only the changed fields are persisted. You can now execute code such as the following example, which only updates the name of the Customer field:

CopyCode image Copy Code
Customer customer = custService.Read("10000");
customer.Name = "The Cannon Group, Inc.";
custService.Update(ref customer);

Creating and updating sales orders through a page-based Web service has changed

The procedure for creating and updating sales orders through a page-based Web service has changed. For more information, see the Handling Sales Orders from Page based Web Services – in NAV 2009SP1 (and RTM) blog post.

Web services do not change the user's default company

In the pre-SP1 version of Microsoft Dynamics NAV 2009, a Web service consumer application would change the user's default company because Web services did not use the concept of a default company. Also, a Web service consumer application could not call a Web service operation to request the default company. In Microsoft Dynamics NAV 2009 SP1, invoking a Web service operation does not change the default company.

BLOB fields in page-based Web services are ignored

In the pre-SP1 version of Microsoft Dynamics NAV 2009, you could not have a BLOB field on any page that you exposed as a Web Service. In Microsoft Dynamics NAV 2009 SP1, the content of the BLOB is not transferred to the Web service consumer. The field is ignored.

If you want access to the value of the BLOB, then you must write some code. For more information, see Transferring binary data to/from WebServices (and to/from COM (Automation) objects).

Codeunits ignore operations with unsupported parameters

Codeunits can now be exposed as Web services even if they contain operations that use parameter types that are not supported by Web services. Such functions are not exposed as operations. Examples of such operations are streams, Automation, and BLOBs.

Connections from either PHP or Java are now supported

In Microsoft Dynamics NAV 2009 SP1, you can use PHP, Java, or other products that use the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) to initiate a Web services connection to Microsoft Dynamics NAV.

If the RoleTailored client, Microsoft Dynamics NAV Server, and SQL Server database are all on separate computers, then you must set the WebServicesUseNTLMAuthentication parameter to true in the CustomSettings.config file, which is the Microsoft Dynamics NAV Server configuration file, before connecting from PHP or Java. See Configuring Microsoft Dynamics NAV Server.

See Also

Concepts

Working with Web Services


Web Services Programming Tips

Web Services Programming Tips

The following sections provide suggestions and describe issues to be aware of as you develop Web service clients for Microsoft Dynamics NAV 2009.

Returning Data from Codeunit Web Services Using XMLports

Returning an XMLport from a Web service allows you to design schemas and to support multiple complex types on a single method call. For example, you can use an XMLport if you need to get a bookmark back as you work with a Page Web service.

See this blog post for a demonstration of this technique.

Using Specified Properties with Visual Studio to Indicate the Presence of a Value in a Field

When you set a field to a value in the code for a Web service client and then send the value back to the Web service, such as when using the Create or Update operation, the field value is not actually updated to anything but its default value. This issue can occur if you are using proxies that are generated by Visual Studio or the tools in the .NET Framework SDK.

This happens because of how autogenerated proxies and the .NET Framework handle values in XML documents that are exchanged between the Web service and the client. The issue is not specific to Microsoft Dynamics NAV.

Consider the schema for the following two fields on this Customer Card Web service:

CopyCode image Copy Code
<xsd:element minOccurs="0" maxOccurs="1" name="Credit_Limit_LCY" type="xsd:decimal" />
<xsd:element minOccurs="0" maxOccurs="1" name="Salesperson_Code" type="xsd:string" />

Both fields are optional, which means that they may or may not be present in the XML document. One field is a decimal type, and the other field is a string because it is declared as a Text data type in Microsoft Dynamics NAV.

If both values are present, then the XML document should contain the following lines:

CopyCode image Copy Code
<Credit_Limit_LCY>1000</Credit_Limit_LCY>
<Salesperson_Code>JR</Salesperson_Code>

But if there is no information about the credit limit, then the document should contain the following line:

CopyCode image Copy Code
<Salesperson_Code>JR</Salesperson_Code>

If the credit limit is zero, then the document should contain the following line:

CopyCode image Copy Code
<Credit_Limit_LCY>0</Credit_Limit_LCY>

For the decimal type and all .NET value types, this "present-or-not" state can be controlled in the proxy objects with a Boolean *Specified property:

CopyCode image Copy Code
if (salesOrder.Credit_Limit_LCYSpecified)
    there is a value present in salesOrder.Credit_Limit_LCY
else
    there is no useful value in salesOrder.Credit_Limit_LCY

Consequently, if you assign a value in the value type, then you should also define it as present by setting the accompanying Boolean *Specified property to true:

CopyCode image Copy Code
salesOrder.Credit_Limit_LCY = 1000;
salesOrder.Credit_Limit_LCYSpecified = true;

To specify that there is no useful value in the value type salesOrder.Credit_Limit_LCY, set the accompanying Boolean *Specified property to false:

CopyCode image Copy Code
salesOrder.Credit_Limit_LCYSpecified = false;

The accompanying value in salesOrder.Credit_Limit_LCY will now be disregarded.

.NET reference types, such as the String class, are handled differently because .NET declarations that are based on those types can be null, which means that they can have an explicit expression of no value present:

CopyCode image Copy Code
if (salesOrder.Salesperson_Code != null)
    there is a value present in salesOrder.Salesperson_Code
else
    there is no value in salesOrder.Salesperson_Code

If you assign a value, then you implicitly also define it as present:

CopyCode image Copy Code
salesOrder.Salesperson_Code = "JR";

To specify that there is no useful value in salesOrder.Salesperson_Code, set it to null:

CopyCode image Copy Code
salesOrder.Salesperson_Code = null;

Example

CopyCode image Copy Code
SalesOrder salesOrder = new SalesOrder();
salesOrder.Order_Date = DateTime.Today;
salesOrder.Order_DateSpecified = true;
salesOrder.Currency_Code = "SEK";

salesOrderService.Create(ref salesOrder);

Preserving Data When Working With a Statically Generated Proxy

You can lose data if you develop a Web service client that interacts with a statically generated proxy. We recommend that you implement a process to prevent this from happening. For example, you can generate your proxy as a part of your automated build of the client.

You can run form 810, Web Services, from the Classic client and publish page 21, Customer Card, as a Web service with Customer as the Service Name value. You can then add a Web reference to this service from a C# console application and insert the following code in the Main method:

C# CopyCode image Copy Code
static void Main(string[] args)
{
  CustomerService.Customer_Service svc
      = new CustomerService.Customer_Service();
  svc.UseDefaultCredentials = true;
  Customer c = svc.Read("01121212");
  Console.WriteLine(c.Name);
  Console.ReadKey();
}

When you run the application, you will see the following output:

CopyCode image Copy Code
Spotsmeyer's Furnishings

You can then go back to page 21 and set the Name property for the control that is bound to the Name field to CustomerName, and save the page.

Finally, you switch back to the console application without updating the Web reference and run the code. Instead of getting an error message that indicates that the Web request does not match the Web service description, you do not get an error message, and Console.WriteLine shows an empty line.

Similarly, a client Web service cannot detect if a field has been removed from a page since a proxy was last generated.

See Also

Concepts

Designing Web Services


Designing Web Services

You can use the topics in this section to learn about designing Web services and to learn about what to be aware of and what tools to use.

Designing Web Services

To | See
Step through the process of registering a page or codeunit as a Web service | How to: Register a Web Service
Learn how to retrieve the list of companies | How to: Use SystemService to Find Companies
Learn about the default page operations that are available when a page is exposed as a Web service | Basic Page Operations
Read about handling any user interface interaction from Web services | Handling UI Interaction When Working with Web Services
Step through creating an extension codeunit for an existing page, exposing the page, and writing code that calls the page | Walkthrough: Creating a Web Service using Extension Codeunits
Step through creating and consuming a simple Web service with Microsoft Dynamics NAV | Walkthrough: Creating and Consuming a Codeunit Web Service
Step through exposing a page as a Web service and manipulating data from that page | Walkthrough: Registering and Consuming a Page Web Service
Make Web service communication more secure | Walkthrough: Configuring Web Services to Use SSL
Note Note

Microsoft Dynamics NAV Server cannot determine the origin time zone for a Web service. Therefore, all Web service communication should be in UTC. All business logic is executed with respect to UTC. For more information, see Communicating with RoleTailored Clients in Different Time Zones.

See Also

Concepts

Microsoft Dynamics NAV Web Services
Creating XMLports
Web Services Programming Tips


How to: Register a Web Service

How to: Register a Web Service

After you have created a Web service or decided that a specific codeunit or page should be exposed as a Web service, you must register the Web service so that it is available for requests over the network. Users can discover Web services from a server by pointing a browser or other tool such as Visual Studio at the computer running Microsoft Dynamics NAV Server and getting a list of available services. When you publish the Web service, it is immediately available over the network for authenticated users.

Registering a Web Service

The following steps explain how to register and publish a Web service. The name that you give the Web service will be visible over the network and should provide a meaningful indication of what the Web service offers.

Note Note

If you are setting up integration with Microsoft Office Outlook using codeunit 5313, then you must use DynamicsNAVsynchOutlook as the service name.

To register and publish a Web service

  1. Open the RoleTailored client.

  2. In the navigation pane, click Departments, click Administration, click IT Administration, click General, and then click Web Services.

  3. In the Web Services page, click New.

  4. In the Object Type column, select Codeunit or Page.

  5. In the Object ID column, select the object ID of the codeunit or page that you want to expose.

  6. In the Service Name field, enter the name of the Web service.

    Note Note

    The service name will be visible to consumers of your Web service, so you should make it meaningful.

  7. Click to insert a check mark in the Published column.

  8. Click OK to exit the New - Web Services page.

See Also

Tasks

Walkthrough: Creating and Consuming a Codeunit Web Service
Walkthrough: Registering and Consuming a Page Web Service

Concepts

Working with Web Services


How to: Use SystemService to Find Companies

How to: Use SystemService to Find Companies

You can use the SystemService service to retrieve a list of companies that are available in a specific database. The appropriate company name must be used in the URL to access other Web services, and this service allows you to retrieve names of available companies.

The following code example shows how to use the SystemService service to retrieve and print a list of companies.

To use the SystemService service to find companies

  1. In Visual Studio, on the File menu, point to New, and then click Project.

  2. Expand the Visual C# node, and then select Console Application. Enter the name FindingCompanies for the application.

  3. In Solution Explorer, right-click the References node in the project, and then click Add Web Reference.

    Note Note

    If you are using Visual Studio 2008, then click Add Service Reference instead.

  4. In the Add Web Reference window, type the URL that you used when checking the WSDL, such as http://localhost:7047/DynamicsNAV/WS/Services, and then click Go.

    Note Note

    In Visual Studio 2008, click the Advanced button, click the Add Web Reference button, type the URL, and then click Go.

  5. When the SystemService service is displayed, click Add Reference. Rename the Web reference name from localhost to SystemService.

  6. On the Program.cs tab, add the following lines of code in bold.

    CopyCode image Copy Code
    namespace UsingSystemService
{
    using SystemService;

    class Program
    {
        static void Main(string[] args)
        {
            // Create instance of service and set credentials.
            SystemService.SystemService service = new SystemService.SystemService();
            service.UseDefaultCredentials = true;
            // The service URL is set by the proxy with a
            // value from the .config file.

            // Load all companies into an array.
            string[] companies = service.Companies();

            // Run through and print all companies.
            // Also print company name in encoded form.
            foreach (string company in companies)
            {
                Console.WriteLine(company);
                Console.WriteLine((Uri.EscapeDataString(company));
            }
            Console.ReadLine();
        }
    }
}

  7. Save and compile the FindingCompanies application.

  8. Press F5 to run the application in debug mode.

See Also

Tasks

Walkthrough: Creating a Web Service using Extension Codeunits
Walkthrough: Creating and Consuming a Codeunit Web Service
Walkthrough: Registering and Consuming a Page Web Service


Basic Page Operations

Basic Page Operations

When you publish a page as a Web service, it has a set of default operations that are exposed to consumers of the Web service.

These operations match the actions a user can perform by interacting with a page using the RoleTailored client. The same page- and table-based business logic is executed.

The following table lists the operations and provides links to reference pages.

Pages that are backed by virtual tables are not editable through Web services. When such pages are published as Web services, the only operations that are available are Read, ReadMultiple, and IsUpdated.

The term entity that is used in the operation signatures describes the data type that is used. The actual entity is defined by the page that is exposed because it contains all controls that are defined on the page. The controls are normally bound to the page's source table. The entity also contains a key that is a special string that uniquely identifies the source table record with a timestamp. This key is used as an argument in many page operations.

All basic page operations are atomic, which means that either all relevant records are affected or no records are affected, even if there was a faulty condition in only one record.

Operation | Description and signature
Create Operation | Creates a single record. void Create(ref Entity entity)
CreateMultiple Operation | Creates a set of records. void CreateMultiple(ref Entity[] entity)
Read Operation | Reads a single record. Entity Read(string no)
ReadMultiple Operation | Reads a filtered set of records, paged. Entity [] ReadMultiple(Entity_Filter[] filterArray, string bookmarkKey, int setSize)
Update Operation | Updates a single record. void Update(ref Entity entity)
UpdateMultiple Operation | Updates a set of records. void UpdateMultiple(ref Entity[] entity)
Delete Operation | Deletes a single record. bool Delete(string key)
IsUpdated Operation | Checks if an object has been updated since the key was obtained. bool IsUpdated(string key)
Delete_<part> Operation | Deletes a subpage of the current page. bool Delete_<part>(string key)

See Also

Tasks

Walkthrough: Registering and Consuming a Page Web Service
Walkthrough: Creating a Web Service using Extension Codeunits


Create Operation

Create Operation

Creates a single record. The supplied record object is overwritten with the version that is created by the page.

Expand image Parameters

Parameter | Description
entity | Type: Entity A variable of a specific object type that represents the page.

Expand image Results

Result name | Description
entity | Type: Entity A variable of a specific object type that represents the page. Contains the latest values that are present on the page after the record has been inserted into the table.

Expand image Faults

SOAP fault message | Description
The [record name] already exists. Identification fields and values: [field]=[value] | Indicates that the record insertion would violate key constraints.

Other faults are possible if they are generated by the C/AL code.

Expand image Usage Example

For a detailed code example, see Walkthrough: Registering and Consuming a Page Web Service.

C# CopyCode image Copy Code
Customer cust = new Customer();
cust.Name = "Customer Name";
service.Create(ref cust);

Expand image See Also

Concepts

Basic Page Operations


CreateMultiple Operation

CreateMultiple Operation

Creates a set of records. The supplied record object is overwritten with the version that is created by the page.

Expand image Parameters

Parameter | Description
entity[] | Type: An array of Entities An array of a specific object type that represents the page.

Expand image Results

Result name | Description
entity[] | Type: An array of Entities An array of a specific object type that represents the page. Contains the latest values that are present on the page after the records have been inserted into the table.

Expand image Faults

SOAP fault message | Description
The [record name] already exists. Identification fields and values: [field]=[value] | Indicates that the insertion of at least one of the records would violate key constraints.

Other faults are possible if they are generated by the C/AL code.

The CreateMultiple operation is executed as a single transaction unless the C/AL code explicitly commits the transaction. Either all or none of the records are inserted unless the application code does not explicitly call COMMIT.

Expand image Usage Example

C# CopyCode image Copy Code
Customer[] custArray = new Customer[3];
for (int i = 0; i < custArray.Length; i++)
{
  custArray[i] = new Customer();
  custArray[i].Name = "Customer Name " + i.ToString();
}
service.CreateMultiple(ref custArray);

Expand image See Also

Concepts

Basic Page Operations


Read Operation

Read Operation

Reads a single record.

Note Note

The signature of an operation changes if the page contains one or more unbound fields in the root content area. If there are unbound fields, then the names from the SourceExpr property for the unbound fields are added as the first parameters to the operation. They are added according to the tab order of the page. For an example, see the Item Journal.

Expand image Parameters

Parameter Description

no

Type: String

The primary key of the requested record.

This argument is a filter on the primary key and returns the first record that matches the filter. When special characters, such as an apostrophe, equal sign, or ampersand, are part of the key, you must surround the argument with quotation marks.

For example, when writing C# code, in addition to standard quotation marks for strings, you should also provide additional single quotes around a value, such as "'A&B'".

Expand image Results

Result name Description

entity

Type: Entity

A variable of a specific object type that represents the page. Contains the latest values that are present on the page.

If the record with the given primary key does not exist, then no value is returned. In .NET, a null reference will be returned.

Expand image Faults

This operation does not return a fault when a matching record is not present. Instead, it returns no value. In C#, you should test if the result is a null reference. Otherwise, you may get a NullReferenceException exception.

Faults are possible if they are generated by the C/AL code.

Expand image Usage Example

C# CopyCode image Copy Code
Customer cust = new Customer();
cust.Name = "Customer Name";
service.Create(ref cust);
cust = service.Read(cust.No);

Expand image See Also

Concepts

Basic Page Operations


ReadMultiple Operation

ReadMultiple Operation

Reads a filtered set of records. This operation returns an array of entities. The ReadMultiple operation allows the consumer of a Web service to specify the number of records to be returned at one time. This can reduce load on the server.

Note Note

Records on a page that were inserted after the page was retrieved are not read. Records on a page may be incorrectly included in the retrieved dataset if they were deleted after the page was retrieved.

Expand image Parameters

Parameter | Description
filterArray | Type: Entity_Filter[] An array of record filters.
bookmarkKey | Type: String The last record bookmark of the page that was previously read. To return the first page of results, set bookmarkKey to NULL.
setSize | Type: Integer The size of the set to be returned. To return the entire set of results, set setSize to zero. To reverse the order of the results, set setSize to negative.

Expand image Results

Result name Description

entity[]

Type: An array of Entities

An array of a specific object type that represents the page. Contains the latest values that are present on the page.

The server will return at most setSize records. If all records have been already returned, then subsequent calls will return no records (a 0-element array in C#). You should keep calling the ReadMultiple function until no records are returned.

entity.Key

Type: String

The key of the last record read. In C#, you can access it with Entity[Entity.Length-1].Key.. Pass this as bookmarkKey for the next ReadMultiple call.

Expand image Faults

This operation does not throw faults when no matching records are present. Instead, it returns an empty record list.

Faults are possible if they are generated by the C/AL code.

Expand image Remarks

Retrieving Last Page

To retrieve the last record of a page, set setSize to -1. Using negative numbers in setSize will sort the records in descending order.

Entity_Filter

You use the Entity_Filter parameter with the ReadMultiple operation. It describes a filter that can be applied on a specific field within a record. The Entity_Filter parameter contains two members: Field and Criteria.

  • Field contains the name of the field that the filter is applied to. This name comes from the Entity_Fields enum.

  • Criteria is of type string and can contain any valid Microsoft Dynamics NAV style filter that is specified in a standard Microsoft Dynamics NAV filter format.

Expand image Usage Examples

The following example returns the first 100 customer names that start with an S. For a detailed code example, see Walkthrough: Registering and Consuming a Page Web Service.

C# CopyCode image Copy Code
List<Customer_Filter> filterArray = new List<Customer_Filter>();
Customer_Filter nameFilter = new Customer_Filter();
nameFilter.Field = Customer_Fields.Name;
nameFilter.Criteria = "S*";
filterArray.Add(nameFilter);
Customer[] custList = service.ReadMultiple(filterArray.ToArray(), null, 100);

This example uses the bookmarkKey argument to read customer records in batches of 10:

C# CopyCode image Copy Code
Customer_Service service = new Customer_Service();
service.UseDefaultCredentials = true;

const int fetchSize = 10;
string bookmarkKey = null;
List<Customer> customerList = new List<Customer>();

// Read customer data in pages of 10.
Customer[] results = service.ReadMultiple(new Customer_Filter[] { }, bookmarkKey, fetchSize);
while (results.Length > 0)
{
    bookmarkKey = results.Last().Key;
    customerList.AddRange(results);
    results = service.ReadMultiple(new Customer_Filter[] { }, bookmarkKey, fetchSize);
}

// Print the collected data.
foreach (Customer customer in customerList)
{
    Console.WriteLine(customer.Name);
}

Expand image See Also

Concepts

Basic Page Operations


Update Operation

Update Operation

Updates a single record. The updated record is passed as a reference and is updated with the latest version.

Expand image Parameters

Parameter | Description
entity | Type: Entity A variable of a specific object type that represents the page.

Expand image Results

Result name | Description
entity | Type: Entity A variable of a specific object type that represents the page. Contains the latest values that are present on the page after the record has been updated by the business logic or another concurrent process.

Expand image Faults

SOAP fault message | Description
Other user has modified [record name]. | Indicates that another user or process has modified the record after it has been retrieved for this update operation.
[record name] [field] [value] does not exist. | Indicates that the record has been deleted by another user or process after it has been retrieved for this update operation.
The [record name] already exists. Identification fields and values: [field]=[value] | Indicates that the renaming of the record would violate key constraints.

Other faults are possible if they are generated by the C/AL code.

Expand image Usage Example

For a detailed code example, see Walkthrough: Registering and Consuming a Page Web Service.

C# CopyCode image Copy Code
Customer cust = new Customer();
cust.Name = "Customer Name ";
service.Create(ref cust);
cust.Name = cust.Name + "Updated";
service.Update(ref cust);

Expand image See Also

Concepts

Basic Page Operations


UpdateMultiple Operation

UpdateMultiple Operation

Updates a set of records. The updated array of records is passed as a reference and is updated with the latest version.

Note Note

The UpdateMultiple operation attempts to update one field at a time. This can cause errors if the updated value in one field prevents another field's value from being valid. You can resolve this by deleting and inserting lines instead of updating.

Expand image Parameters

Parameter | Description
entity[] | Type: An array of Entities. An array of a specific object type that represents the page.

Expand image Results

Result name | Description
entity[] | Type: An array of Entities An array of a specific object type that represents the page. Contains the latest values that are present on the page after the records have been updated by the business logic or another concurrent process.

Expand image Faults

SOAP fault message | Description
Other user has modified [record name]. | Indicates that another user or process has modified the record after it has been retrieved for this update operation.
[record name] [field] [value] does not exist. | Indicates that the record has been deleted by another user or process after it has been retrieved for this update operation.
The [record name] already exists. Identification fields and values: [field]=[value] | Indicates that the renaming of the record would violate key constraints.

Other faults are possible if they are generated by the C/AL code.

The UpdateMultiple operation is executed as a single transaction unless the C/AL code explicitly commits the transaction. Either all or none of the records are updated provided that the application code does not explicitly call COMMIT.

Expand image Usage Example

The following example adds the string "Updated" to the name of the first 100 customer names that start with S.

C# CopyCode image Copy Code
List<Customer_Filter> filterArray = new List<Customer_Filter>();
Customer_Filter nameFilter = new Customer_Filter();
nameFilter.Field = Customer_Fields.Name;
nameFilter.Criteria = "S*";
filterArray.Add(nameFilter);
Customer[] custList = service.ReadMultiple(filterArray.ToArray(), null, 100);
for (int i = 0; i < custList.Length; i++)
{
  custList [i].Name = custList [i].Name + " Updated";
}
service.Update(ref custList)

Expand image See Also

Concepts

Basic Page Operations


Delete Operation

Delete Operation

Deletes a single record.

Executing the Delete operation in a Web service first executes the OnDeleteRecord Trigger on the designated page. If application code in the OnDeleteRecord trigger for the page returns true, then the OnDelete Trigger for the corresponding table is executed. If no fault occurs, the record is deleted from the database.

If the application code in the trigger returns false, then the OnDelete trigger is not executed. This does not necessarily mean that the record has not been deleted, because it may have been deleted explicitly by the application code for the page's OnDeleteRecord trigger.

The return value from the Delete operation is the return value from the page's OnDeleteRecord trigger.

If Delete returns true, then the record has been deleted. If Delete has thrown a fault, then the record has not been deleted. But when Delete returns false, then this indicates that there was application logic involved, and the record may or may not have been deleted.

Expand image Parameters

Parameter | Description
Key | Type: String The bookmark of the record, including both primary key and concurrency information.

Expand image Results

Result name | Description
Delete_Result | Type: Boolean The value returned by the OnDeleteRecord page trigger.

Expand image Faults

SOAP fault message | Description
Other user has modified [record name]. | Indicates that another user or process has modified the record after it has been retrieved for this delete operation.
[record name] [field] [value] does not exist. | Indicates that the record has been deleted by another user or process after it has been retrieved for this delete operation.

Other faults are possible if they are generated by the C/AL code.

Expand image Usage Example

C# CopyCode image Copy Code
using System;
using System.Collections.Generic;
using System.Text;

namespace ConsoleApplication
{
    // Import newly generated Web service proxy.
    using WebService;

    class Program
    {
        static void Main(string[] args)
        {
            // Create instance of service and set credentials.
            Customer_Service service = new Customer_Service();
            service.UseDefaultCredentials = true;
            Customer cust = new Customer();
            cust.Name = "Customer Name";
            service.Create(ref cust);
            cust = service.Read(cust.No);
            service.Delete(cust.Key);
        }
    }
}

Expand image See Also

Concepts

Basic Page Operations


IsUpdated Operation

IsUpdated Operation

Checks if an object has been updated since the key was obtained. This operation returns true if the object has been updated by any user; otherwise, false. Concurrency management will prevent a record being changed if it has been subsequently updated. This check will proactively prevent that failure.

Expand image Parameters

Parameter | Description
Key | Type: String The bookmark of the record, including both primary key and concurrency information.

Expand image Results

Result name | Description
IsUpdated_Result | Type: Boolean Returns true if and only if another user has modified the record.

Expand image Faults

SOAP fault message | Description
[record name] [field] [value] does not exist. | Indicates that the record has been deleted by another user or process after it has been retrieved for this operation.

Expand image Usage Example

C# CopyCode image Copy Code
using System;
using System.Collections.Generic;
using System.Text;

namespace ConsoleApplication
{
    // Import newly generated Web service proxy.
    using WebService;

    class Program
    {
       static void Main(string[] args)
           {
              // Create instance of service and set credentials.
              Customer_Service service = new Customer_Service();
              service.UseDefaultCredentials = true;

              Customer cust = new Customer();
              cust.Name = "Customer Name";
              service.Create(ref cust);
              cust = service.Read(cust.No);
              if (!service.IsUpdated(cust.Key))
           {
              // Add code here to modify record.
           }
        }
    }
}

Expand image See Also

Concepts

Basic Page Operations


Delete_<part> Operation

Delete_<part> Operation

Deletes records on a subpage of the current page.

This operation is exposed only by pages that have subpages, which are pages that have parts of type page. For example, the Sales Order page has a part with the name SalesLines, which has PartType equal to Page and PagePartID equal to “Sales Order Subform.” The name of the operation that is exposed by the Sales Order page is therefore Delete_SalesLines.

When you call this operation, you delete a record of the subpage. When you call Read on a page that has a subpage, you get the records of the top level page and the corresponding records of the subpage. To modify them or add to them, you must modify the entire top-level record.

Executing the Delete_<part> operation in a Web service first executes the OnDeleteRecord Trigger on the designated record of the subpage. If application code in the OnDeleteRecord trigger for the record of the subpage returns true, then the OnDelete Trigger for the corresponding table is executed. If no fault occurs, the record of the subpage is deleted from the database.

If the application code in the trigger returns false, then the OnDelete trigger is not executed. But this does not necessarily mean that the record of the subpage has not been deleted, because it may have been deleted explicitly by the application code for the page's OnDeleteRecord trigger.

The return value from the Delete_<part> operation is the return value from the page's OnDeleteRecord trigger.

If Delete returns true, thenthe record of the subpage has been deleted. If Delete has thrown a fault, then the record of the subpage has not been deleted. But when Delete returns false, then this indicates that there was application logic involved, and the record of the subpage may or may not have been deleted.

Expand image Parameters

Parameter | Description
Key | Type: String The bookmark of the record of the subpage, including both primary key and concurrency information.

Expand image Results

Result name | Description
Delete_Result | Type: Boolean The value that is returned by the OnDeleteRecord page trigger.

Expand image Faults

SOAP fault message | Description
Other user has modified [record name]. | Indicates that another user or process has modified the record of the subpage after it has been retrieved for this delete operation.
[record name] [field] [value] does not exist. | Indicates that the record of the subpage has been deleted by another user or process after it has been retrieved for this delete operation.

Other faults are possible if they are generated by the C/AL code.

Expand image Usage Example

This example presents a console application that is created in Visual Studio after registering and publishing the Sales Order page. For details on how to register and publish a page, see Walkthrough: Registering and Consuming a Page Web Service. After you publish the page as a Web service, you must also add a Web reference to it. This task is also described in the walkthrough.

C# CopyCode image Copy Code
using Delete_SalesLinesSample.DynamicsNAVService;

namespace Delete_SalesLinesSample
{
    class Program
    {
        static void Main(string[] args)
        {
            DynamicsNAVService.SalesOrder_Binding so = new SalesOrder_Binding();
            so.UseDefaultCredentials = true;

            SalesOrder salesOrder = so.Read("2001");
            Sales_Order_Line[] salesLines = salesOrder.SalesLines;

            if (salesLines.Length > 0)
            {
                string key = salesLines[0].Key;
                so.Delete_SalesLines(key);
            }
        }
    }
}

Expand image See Also

Concepts

Basic Page Operations


Handling UI Interaction When Working with Web Services

Handling UI Interaction When Working with Web Services

Whether you expose or consume Web services, exceptions and dialogs that appear during execution of the code must be handled properly. Exceptions must be handled to prevent the system from ending the Web service execution. There are two ways of handling exceptions—by writing conditional code inside Microsoft Dynamics NAV, or by writing the code where the Web service is called. The best solutions use both methods for safety.

When Exposing Web Services

The developer who exposes a Web service must consider issues that may arise. Specifically, the developer should be sure that the code doesn't require any interaction with a user. The primary way of suppressing UI is the implementation of a GUIALLOWED statement that checks, for example, if a codeunit is called from Microsoft Dynamics NAV or from a Web service. You do not want to throw any errors if a codeunit is called from a Web service.

When implementing a conditional code check inside Microsoft Dynamics NAV, implement the check only around code that could cause an error. Do not encapsulate the whole business logic in this check.

Note Note

The server returns the following exception when trying to invoke a dialog UI through a Web service: Microsoft.Dynamics.Nav.Types.Exceptions.NavNCLCallbackNotAllowedException: Callback functions are not allowed.

DIALOG Function

The DIALOG function in C/AL is for storing dialog windows. Any code that uses this function must be considered when working with Web services. The following table lists the methods and their behavior when called from a Web service.

Behavior when called from a Web service | Method name
Is accepted and doesn't cause an exception. | MESSAGE
Throws an exception. | BEEP CLOSE CONFIRM ERROR INPUT OPEN STRMENU UPDATE YIELD

When Consuming Web Services

Remember also to handle exceptions in code that calls a Web service. When implementing a code check outside of Microsoft Dynamics NAV, appropriate exception capturing code should be included around any call to a Microsoft Dynamics NAV Web service.

See Also

Tasks

How to: Register a Web Service
Walkthrough: Creating a Web Service using Extension Codeunits
Walkthrough: Creating and Consuming a Codeunit Web Service
Walkthrough: Registering and Consuming a Page Web Service

Concepts

Microsoft Dynamics NAV Web Services
Basic Page Operations


Walkthrough: Creating and Consuming a Codeunit Web Service

Walkthrough: Creating and Consuming a Codeunit Web Service

Web services allow easy communication and data exchange in a secured environment. In Microsoft Dynamics NAV 2009, you can create, publish, and consume Web services. For example, you can publish a Web service that lists all your customers and have that Web service immediately available for authorized requests over the network.

Expand image About This Walkthrough

This walkthrough provides an overview of how to create and consume a simple Web service with Microsoft Dynamics NAV. The walkthrough illustrates to the following tasks:

  • Creating a codeunit from within Microsoft Dynamics NAV.

  • Exposing the Web service.

  • Verifying the Web services availability.

  • Consuming the Web service from a console application that is created in Visual Studio.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • Visual Studio 2005, Visual Studio 2008, Visual C# 2008 Express Edition, or any version of Visual Studio that supports adding Web references. You can also use service references instead of Web references or the Web service proxy generating tools (svcutil.exe or wsdl.exe) that are supplied in the Microsoft .NET Framework SDK.

Expand image Creating a Codeunit

The first step is to create a codeunit that can be published and used as a Web service. You will create a codeunit called Letters that takes a lowercase input string and returns a string that is converted to uppercase letters.

To create a codeunit

  1. Open the Classic client and connect to the CRONUS International Ltd. demonstration company.

  2. On the Tools menu, click Object Designer.

  3. In Object Designer, click Codeunit, and then click New.

  4. On the View menu, click C/AL Globals.

  5. In the C/AL Globals window, click the Functions tab, and then enter Capitalize as the function name.

  6. In the C/AL Globals window, click the Locals button.

  7. On the Parameters tab, enter inputstring in the Name field, and then select Text in the DataType field. Set the length to 250.

  8. On the Return Value tab, enter outputstring in the Name field, and then select Text in the Return Type field. Set the length to 250.

  9. Close the C/AL Locals window, and then close the C/AL Globals window.

  10. In the Capitalize method, insert the following line of code:

    CopyCode image Copy Code
    outputstring := UPPERCASE(inputstring);

  11. Save and close the C/AL Editor.

  12. When prompted, give the codeunit the ID 50000 and the name Letters.

Expand image Registering the Web Service

After the codeunit is created and saved, register and publish it using the RoleTailored client.

To register and publish the Web service

  1. Open the RoleTailored client and connect to the CRONUS International Ltd. demonstration company.

  2. In the navigation pane, click Departments, click Administration, click IT Administration, click General, and then click Web Services.

  3. In the Web Services page, click New.

  4. In the Object Type column select Codeunit, and then enter 50000 in the Object ID column ID and Letters in the Service Name column.

  5. Click to select the field in the Published column.

  6. Click OK to close the New - Web Services page.

Expand image Verifying the Web Services Availability

You should verify that the Web service that you published is available to consumers. Check that Web services are running, and then browse to the WSDL document to ensure that your Web service is available.

Note Note

When exposing a Web service, you must open the port for other consumers of your Web service to access it. Have your system administrator open the port through Windows Firewall on the computer running Microsoft Dynamics NAV Server. The default port is set to 7047 and can be configured in the CustomSettings.config file on Microsoft Dynamics NAV Server. For more information, see Configuring Microsoft Dynamics NAV Server.

To start the Microsoft Dynamics NAV Business Web Services service

  1. Click Start on the computer, point to All Programs, point to Administrative Tools, and then click Services.

  2. In the Services tool, right-click Microsoft Dynamics NAV Business Web Services, and then click Start.

  3. Close the Services tool.

If the service is already running, then you must restart it. For information on starting, stopping, and configuring Windows services, see How to: Configure Windows Services.

To verify availability of the specific Web service

  1. Start Internet Explorer.

  2. In the Address field, enter the following address where the keys are replaced with the values that are specified in the CustomSettings.config file: http://<Server>:<WebServicePort>/<ServerInstance>/WS/<CompanyName>/services. An example WSDL URL is:

    http://localhost:7047/DynamicsNAV/WS/CRONUS%20International%20Ltd./services

    Note Note

    The company name is optional and case-sensitive.

    The page should list the Web service that you just published (Codeunit/Letters).

  3. Close the browser.

Expand image Consuming the Web Service

Now that the Web service is available, you can create an application to call the Web service.

To call the Web service

  1. In Visual Studio, on the File menu, point to New, and then click Project.

  2. Expand the Visual C# node, select Windows, and then, under Visual Studio installed templates, select Console Application. Enter the name UsingLettersService for the application.

    The sample code in this walkthrough expects this exact application name, so do not change it.

  3. Click OK to close the New Project page.

  4. In Solution Explorer, right-click the References node in the project, and then click Add Service Reference.

    Note Note

    If you are using Visual Studio 2005, then click Add Web Reference instead.

  5. In Visual Studio 2008, click the Advanced button, click the Add Web Reference button, type or paste the URL that you used when checking the WSDL, such as http://localhost:7047/DynamicsNAV/WS/Services, and then click Go.

    Note Note

    In Visual Studio 2005, type or paste the URL in the Add Web Reference window, and then click Go.

  6. When the Letters service is displayed, click View Service, rename localhost to WebService, and then click Add Reference.

  7. On the Program.cs tab, replace the existing code with the following code:

    C# CopyCode image Copy Code
    using System;
using System.Collections.Generic;
using System.Text;

namespace UsingLettersService
{
    // Import newly generated Web service proxy.
    using WebService;

    class Program
    {
        static void Main(string[] args)
        {
            // Create a new instance of the service.
            Letters ws = new Letters();

            // Use default credentials for authenticating
            // against Microsoft Dynamics NAV.
            ws.UseDefaultCredentials = true;
            ws.Url = "http://localhost:7047/DynamicsNAV/WS/CRONUS%20International%20Ltd./Codeunit/Letters";

            // Declare variables to work with.
            string inputstring, outputstring;
            inputstring = "microsoft dynamics nav web services!";

            // Call the Microsoft Dynamics NAV codeunit Web service.
            outputstring = ws.Capitalize(inputstring);

            // Write output to the screen.
            Console.WriteLine("Result: {0}", outputstring);

            // Keep the console window open until you press ENTER.
            Console.ReadLine();
        }
    }
}

  8. Press F5 to run the application in debug mode. You should see a console window that prints the text 'MICROSOFT DYNAMICS NAV WEB SERVICES!' in uppercase letters.

  9. Press Enter to close the application.

Expand image Next Steps

This walkthrough illustrated how you can publish a codeunit as a Web service from Microsoft Dynamics NAV and write a program that uses the Web service. The next step is to expose a page as a Web service and then interact with data from that page. For details, see Walkthrough: Registering and Consuming a Page Web Service.

Expand image See Also

Tasks

How to: Register a Web Service
Walkthrough: Configuring Web Services to Use SSL

Concepts

Working with Web Services
Microsoft Dynamics NAV Web Services
Examples of Web Services


Walkthrough: Registering and Consuming a Page Web Service

Walkthrough: Registering and Consuming a Page Web Service

With Microsoft Dynamics NAV 2009, you can create, publish, and consume Web services. This walkthrough focuses on registering and consuming a page as a Web service. When a page is published as a Web service, a default set of operations is exposed to developers for managing common record-handling tasks. The walkthrough shows how to use some of these operations.

Expand image About This Walkthrough

This walkthrough provides an overview of how to expose a page as a Web service and how to manipulate data from that page. The walkthrough illustrates the following tasks:

  • Registering and publishing an existing page as a Web service.

  • Verifying the service's availability using the WSDL.

  • Consuming the Web service from a console application that is created in Visual Studio.

  • Making calls to the Create, Read, Update, and Delete functions on a Page Web service.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • Visual Studio 2005, Visual Studio 2008, Visual C# 2008 Express Edition, or any version of Visual Studio that supports adding Web references. You can also use service references instead of Web references or the Web service proxy generating tools (svcutil.exe or wsdl.exe) that are supplied in the Microsoft .NET Framework SDK.

Expand image Registering and Publishing a Page as a Web Service

You register and publish a Web service using the RoleTailored client.

To register and publish a page as a Web service

  1. Open the RoleTailored client and connect to the CRONUS International Ltd. demonstration company.

  2. In the navigation pane, click Departments, click Administration, click IT Administration, click General, and then click Web Services.

  3. In the Web Services page, click New.

  4. In the Object Type column, select Page, and then enter 21 in the Object ID column and Customer in the Service Name column.

  5. Click to insert a check mark in the Published column.

  6. Click OK to exit the New - Web Services page.

Expand image Verifying the Web Services Availability

You should verify that the Web service is available to consumers. Start the Microsoft Dynamics NAV Web services service, and then browse to the WSDL document to ensure that your Web service is available.

Note Note

When exposing a Web service, you must open the port for consumers of your Web service to access it. Have your system administrator add the port through Windows Firewall on the computer running Microsoft Dynamics NAV Server. The default port is set to 7047 and can be configured in the CustomSettings.config file on the Microsoft Dynamics NAV Server computer. For more information, see Configuring Microsoft Dynamics NAV Server.

To start the Microsoft Dynamics NAV Business Web Services service

  1. Click Start on the computer running Microsoft Dynamics NAV Server, point to All Programs, point to Administrative Tools, and then click Services.

  2. Right-click Microsoft Dynamics NAV Business Web Services, and then click Start on the shortcut menu.

  3. Close the window.

If the service is already running, you must restart it. For information on starting, stopping, and configuring Windows services, see How to: Configure Windows Services.

To verify availability of the Web service

  1. Start Internet Explorer.

  2. In the Address field, enter the following address where the keys are replaced with the values that are specified in the CustomSettings.config file: http://<Server>:<WebServicePort>/<ServerInstance>/WS/<CompanyName>/services. An example WSDL URL is:

    http://localhost:7047/DynamicsNAV/WS/CRONUS%20International%20Ltd./services

    Note Note

    The company name is optional and case-sensitive.

    The page should list the Web service that you have published: Page/Customer.

  3. Close the browser.

Expand image Calling the Web Service

Now that the Web service is exposed, use Visual Studio to create an application that calls the Web service. This procedure assumes that you are using Visual Studio 2008 but provides alternate steps for Visual Studio 2005.

To call the Web service

  1. In Visual Studio, on the File menu, point to New, and then click Project.

  2. Expand the Visual C# node, select Windows, and then, under Visual Studio installed templates, select Console Application. Enter the name PrintCustomerList for the application.

    The sample code in this walkthrough expects this exact application name, so do not change it.

  3. Click OK to exit the New Project page.

  5. In Solution Explorer, right-click References in the project, and then click Add Service Reference.

    Note Note

    If you are running Visual Studio 2005, then click Add Web Reference instead.

  6. In Visual Studio 2008, click the Advanced button, click the Add Web Reference button, type or paste the URL that you used when checking the WSDL, such as http://localhost:7047/DynamicsNAV/WS/Services, and then click Go.

    Note Note

    In Visual Studio 2005, type or paste the URL in the Add Web Reference window, and then click Go.

  7. When the Customer service is displayed, click View Service, rename localhost to WebService, and then click Add Reference.

  8. On the Program.cs tab, replace the existing code with the following code:

    C# CopyCode image Copy Code
    using System;
using System.Collections.Generic;
using System.Text;

namespace PrintCustomerList
{
    // Import newly generated Web service proxy.
    using WebService;

    class Program
    {
        static void Main(string[] args)
        {
            // Create instance of service and set credentials.
            Customer_Service service = new Customer_Service();
            service.UseDefaultCredentials = true;
            // Create instance of customer.
            Customer cust = new Customer();
            cust.Name = "Customer Name";
            Msg("Pre Create");
            PrintCustomer(cust);

            // Insert customer.
            service.Create(ref cust);
            Msg("Post Create");
            PrintCustomer(cust);

            // Create filter for searching for customers.
            List<Customer_Filter> filterArray = new List<Customer_Filter>();
            Customer_Filter nameFilter = new Customer_Filter();
            nameFilter.Field = Customer_Fields.Name;
            nameFilter.Criteria = "C*";
            filterArray.Add(nameFilter);

            Msg("List before modification");
            PrintCustomerList(service, filterArray);

            cust.Name = cust.Name + "Updated";
            service.Update(ref cust);

            Msg("Post Update");
            PrintCustomer(cust);

            Msg("List after modification");
            PrintCustomerList(service, filterArray);
            service.Delete(cust.Key);

            Msg("List after deletion");
            PrintCustomerList(service, filterArray);

            Msg("Press [ENTER] to exit program!");
            Console.ReadLine();
        }

        // Print list of filtered customers.
        static void PrintCustomerList(Customer_Service service, List<Customer_Filter> filter)
        {
            Msg("Printing Customer List");

            // Run the actual search.
            Customer[] list = service.ReadMultiple(filter.ToArray(), null, 100);
            foreach (Customer c in list)
            {
                PrintCustomer(c);
            }
            Msg("End of List");
        }

        static void PrintCustomer(Customer c)
        {
            Console.WriteLine("No: {0} Name: {1}", c.No,c.Name);
        }

        static void Msg(string msg)
        {
            Console.WriteLine(msg);
        }
    }
}

  9. Press F5 to run the application in debug mode. You should now see a console window that prints a list of customers from the CRONUS International Ltd. demo company. Note how one customer in the list is created, then modified, and finally deleted.

Expand image See Also

Tasks

How to: Register a Web Service
Walkthrough: Creating and Consuming a Codeunit Web Service
Walkthrough: Configuring Web Services to Use SSL

Concepts

Working with Web Services
Microsoft Dynamics NAV Web Services
Examples of Web Services


Walkthrough: Creating a Web Service using Extension Codeunits

Walkthrough: Creating a Web Service using Extension Codeunits
See Also
CollapseAll image

This walkthrough shows how you can publish and consume a Microsoft Dynamics NAV 2009 page as a Web service and how you can extend the default set of operations that are available on a page with codeunit functionality. Adding an extension codeunit to a page is useful if you want to perform operations other than create, read, update, or delete.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Registering and publishing a page as a Web service.

  • Creating an extension codeunit.

  • Connecting the extension codeunit to the published page.

  • Verifying the service's availability.

  • Calling the Web service from a console application created in Visual Studio.

Prerequisites

To complete this walkthrough, you need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • Visual Studio 2005, Visual Studio 2008, Visual C# 2008 Express Edition, or any version of Visual Studio that supports adding Web references. You can also use service references instead of Web references or the Web service proxy generating tools (svcutil.exe or wsdl.exe) that are supplied in the Microsoft .NET Framework SDK.

Expand image Registering and Publishing a Page as a Web Service

You register and publish a Web service using the RoleTailored client.

To register and publish a page as a Web service

  1. Open the RoleTailored client and connect to the CRONUS International Ltd. demonstration company.

  2. In the navigation pane, click Departments, click Administration, click IT Administration, click General, and then click Web Services.

  3. In the Web Services page, click New.

  4. In the Object Type column, select Page, and then enter 21 in the Object ID column ID and PageWithCapitalization in the Service Name column.

  5. Click to select the field in the Published column.

  6. Click OK to close the New - Web Services page.

    Do not close the RoleTailored client or navigate away from the Web Services page.

Expand image Creating an Extension Codeunit

After you publish the page, you create a codeunit that extends its functionality. Follow the steps in this procedure to create a codeunit called CapitalizeName, which takes a customer name as input and outputs the same customer name capitalized. The codeunit must take the record type of the page as the first parameter.

To create an extension codeunit

  1. Open the Classic client and connect to the CRONUS International Ltd. demonstration company.

  2. On the Tools menu, click Object Designer.

  3. In Object Designer, click Codeunit, and then click New.

  4. On the View menu, click C/AL Globals.

  5. In the C/AL Globals window, click the Functions tab, and then enter CapitalizeName as the name of the function.

  6. From the C/AL Globals window, click the Locals button.

  7. On the Parameters tab, enter Cust in the Name field, and then select Record in the DataType field.

  8. In the SubType field, click the arrow to open the Table list window and select Customer.

  9. Click OK to close the Table list window.

  10. Close the C/AL Locals window, and then close the C/AL Globals window.

  11. In the CapitalizeName method, insert the following lines of code:

    CopyCode image Copy Code
    Cust.Name := UPPERCASE(Cust.Name);
Cust.MODIFY(TRUE);

  12. Close the C/AL Editor.

  13. When prompted, give the codeunit the ID 50012 and the name CapitalizeName.

Expand image Connecting the Codeunit to the Exposed Page

After the codeunit is created and saved, register it under the published page so that the codeunit extends the published page. The codeunit itself should not be marked as Published.

To connect the codeunit to the exposed page

  1. Switch back to the RoleTailored client and the Web Services page.

  2. Click New.

  3. In the Object Type field, select Codeunit, and then select object ID 50012. In the Service Name field, enter PageWithCapitalization, which is the same name that you gave the page Web service.

  4. Clear the Published check box.

  5. Click OK to close the New - Web Services page.

Expand image Verifying Web Services Availability

You should verify that the Web service is available to consumers. Start the Microsoft Dynamics NAV Business Web Services service, and then browse to the WSDL document to ensure that your Web service is available.

Note Note

When exposing a Web service, you must open the port for other consumers of your Web service to access it. Have your system administrator add the port through Windows Firewall on the computer running Microsoft Dynamics NAV Server. The default port is set to 7047 and can be configured in the CustomSettings.config file on Microsoft Dynamics NAV Server. For more information, see Configuring Microsoft Dynamics NAV Server.

To start the Microsoft Dynamics NAV Business Web Services service

  1. Click Start on the computer, point to All Programs, point to Administrative Tools, and then click Services.

  2. Right-click Microsoft Dynamics NAV Business Web Services, and then click Start on the shortcut menu.

  3. Close the window.

If the service is already running, then you must restart it. For information on starting, stopping, and configuring Windows services, see How to: Configure Windows Services.

To verify availability of the Web service

  1. Start Internet Explorer.

  2. In the Address field, enter the following address where the keys are replaced with the values that are specified in the CustomSettings.config file: http://<Server>:<WebServicePort>/<ServerInstance>/WS/<CompanyName>/services. An example WSDL URL is:

    http://localhost:7047/DynamicsNAV/WS/CRONUS%20International%20Ltd./services

    Note Note

    The company name is optional and case-sensitive.

    The page should list the Web services that you have published: Page/PageWithCapitalization and Codeunit/PageWithCapitalization.

  3. Close the browser.

Expand image Calling the Web Services

Now you can create an application that uses both the page and the codeunit Web services. When you add a reference in Visual Studio, methods from both the page and the extension codeunit are available.

To call the Web services

  1. In Visual Studio, on the File menu, point to New, and then click Project.

  2. Expand the Visual C# node, select Windows, and then, under Visual Studio installed templates, select Console Application. Enter the name UsingExtensionCodeunit for the application.

    The sample code in this walkthrough expects this exact application name, so do not change it.

  3. Click OK to close the New Project page.

  4. In Solution Explorer, right-click the References node in the project, and then click Add Service Reference.

    Note Note

    If you are using Visual Studio 2005, then click Add Web Reference instead.

  5. In Visual Studio 2008, click the Advanced button, click the Add Web Reference button, type or paste the URL that you used when checking the WSDL, such as http://localhost:7047/DynamicsNAV/WS/Services, and then click Go.

    Note Note

    In Visual Studio 2005, type or paste the URL in the Add Web Reference window, and then click Go.

  6. When the services are displayed, select the Page service (Page/PageWithCapitalization). Do not select the Codeunit service (Codeunit/PageWithCapitalization). Then click View Service.

  7. Rename localhost to WebService, and then click Add Reference.

  8. On the Program.cs tab , replace the existing code with the following code:

    C# CopyCode image Copy Code
    using System;
using System.Collections.Generic;
using System.Text;

namespace UsingExtensionCodeunit
{
    using WebService;

    class Program
    {
        static void Main(string[] args)
        {
            // Create instance of service and set credentials.
            PageWithCapitalization_Service service = new PageWithCapitalization_Service();
            service.UseDefaultCredentials = true;

            // Create instance of customer.
            PageWithCapitalization cust = new PageWithCapitalization();
            cust.Name = "Louis Taylor";

            // Insert customer using the default operation.
            service.Create(ref cust);
            Console.WriteLine(cust.Name);

            // Call extension codeunit to capitalize customer name.
            service.CapitalizeName(cust.Key);

            // Refresh customer.
            cust = service.Read(cust.No);
            Console.WriteLine(cust.Name);
            Console.ReadLine();
            service.Delete(cust.Key);
        }
    }
}

  9. Press F5 to run the application in debug mode. You should now see a console window that creates a new customer using a default page operation and then capitalizes the customer name using the extension codeunit.

Expand image See Also

Tasks

Walkthrough: Creating and Consuming a Codeunit Web Service
Walkthrough: Registering and Consuming a Page Web Service
Walkthrough: Configuring Web Services to Use SSL

Concepts

Microsoft Dynamics NAV Web Services
Basic Page Operations
Handling UI Interaction When Working with Web Services


Walkthrough: Configuring Web Services to Use SSL

Walkthrough: Configuring Web Services to Use SSL

Secure Sockets Layer (SSL) is a cryptographic protocol that provides security and data integrity for data communications over a network. By encrypting your Microsoft Dynamics NAV 2009 Web services with SSL, you make your data and your network more secure and more reliable.

Expand image Microsoft Dynamics NAV Web Services and SSL

Microsoft Dynamics NAV supports SSL authentication. The server authenticates itself to the client, but the client does not authenticate itself to the server. When the Web service client connects to the Microsoft Dynamics NAV Business Web Services server, the server replies by sending its digital certificate to the client. This certificate contains the server's public encryption key and the name of the authority that granted the certificate. The client verifies the certificate using the authority's public key.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Configuring Microsoft Dynamics NAV Web services to use SSL.

  • Obtaining a certificate and import it into the local computer store on the computer running Microsoft Dynamics NAV Server.

  • Obtaining the certificate's thumbprint.

  • Configuring the Access Control List and the Web services port to use the SSL certificate.

  • Verifying the configuration.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • Visual Studio 2005, Visual Studio 2008, or Visual C# 2008 Express Edition.

Expand image Story

Victor, who is a business systems developer at CRONUS International Ltd., knows that his implementation of Web services applications for Microsoft Dynamics NAV is unlikely to pass a company security audit unless he does something to encrypt sensitive data that is transmitted over the company intranet. He decides to protect Web services communication with SSL.

Expand image Configuring Microsoft Dynamics NAV Web Services to Use SSL

The first step is to prepare Microsoft Dynamics NAV to use SSL. This involves configuring the Microsoft Dynamics NAV Server configuration file to specify SSL and then starting the Microsoft Dynamics NAV Business Web Services service.

To configure Microsoft Dynamics NAV Server to use SSL

  1. Use a text editor to edit the CustomSettings.config file on the computer where you have installed Microsoft Dynamics NAV Server. The default location is C:\Program Files\Microsoft Dynamics NAV\60\Service.

  2. Change the value of the WebServiceSSLEnabled parameter from false to true. Save the file, and then close the editor.

  3. In Control Panel, click Administrative Tools, and then click Services.

  4. In the list of services, find Microsoft Dynamics NAV Business Web Services. Double-click to open the Properties dialog box for this service, and then click Start. If the service is already running, click Stop, and then click Start.)

    This service is not configured to start automatically when you start the computer. If you want this service to start automatically, on the Properties dialog box for this service, on the General tab, select Automatic as the value for Startup type.

    Note Note

    By default, the Microsoft Dynamics NAV Business Web Services service logs on using the NT Authority\Network Service account. We recommend that you configure this service to log on using a dedicated Windows domain user account. This account should not be an administrator either in the domain or on any local computer. Because the Microsoft Dynamics NAV Server service and the Microsoft Dynamics NAV Business Web Services service run on a single process, they must be run using the same account.

  5. Close the Services tool.

Expand image Obtaining and Importing an SSL Certificate

You obtain an SSL certificate from a certificate authority. Some large organizations may have their own certificate authorities, and other organizations can request a certificate from a third-party organization. Once you obtain a certificate, you must import it into the local computer store on the computer running Microsoft Dynamics NAV Server.

The certificate is a file. Use the following procedure to import the certificate into the local computer store.

To import an SSL certificate into the local computer store

  1. On the computer running Microsoft Dynamics NAV Server, click Start, and then click Run.

  2. In the Open box, type mmc, and then click OK.

  3. On the File menu, click Add/Remove Snap-in.

    This procedure assumes that you do not already have the Certificates snap-in installed in Microsoft Management Console. If the Certificates snap-in is already installed, you can skip steps 3 through 9.

  4. In the Add/Remove Snap-in dialog box, click Add.

  5. In the Add Standalone Snap-in dialog box, click Certificates, and then click Add.

  6. In the Certificates snap-in dialog box, click Computer account, and then click Next.

  7. In the Select Computer dialog box, click Local computer, and then click Finish.

  8. In the Add Standalone Snap-in dialog box, click Close.

  9. In the Add/Remove Snap-in dialog box, click OK.

  10. In the left pane of the console, double-click Certificates (Local Computer).

  11. Right-click Personal, point to All Tasks, and then click Import.

  12. On the Welcome to the Certificate Import Wizard page, click Next.

  13. On the File to Import page, click Browse, locate your certificate file, and then click Next.

  14. If the certificate has a password, type the password on the Password page, and then click Next.

  15. On the Certificate Store page, click Place all certificates in the following store, and then click Next.

  16. Click Finish, and then click OK to confirm that the import was successful.

Expand image Obtaining the Certificate's Thumbprint

To perform this task, you continue working in the Certificates snap-in in Microsoft Management Console.

To obtain the certificate's thumbprint

  1. In the left pane of the Console Root window, click Certificates (Local Computer).

  2. Click the Personal folder to expand it.

  3. Click the Certificates folder to expand it.

  4. Double-click the certificate that you just imported.

  5. In the Certificate dialog box, click the Details tab.

  6. Scroll through the list of fields, and then click Thumbprint.

  7. Copy the hexadecimal characters from the box, and then paste them in Notepad.

  8. Delete all spaces in the thumbprint.

Expand image Configuring the Access Control List and the Web Services Port

These procedures use the httpcfg tool for configuring the HTTP server. When you install Microsoft Dynamics NAV Server, Setup puts a copy of httpcfg.exe in the Microsoft Dynamics NAV Server directory. By default, this directory is C:\Program Files\Microsoft Dynamics NAV\60\Service.

An Access Control List (ACL) is part of the Windows security infrastructure. For more information, see Access Control Lists.

To configure the Access Control List

  1. At the command prompt, navigate to the directory where httpcfg.exe is located.

  2. View the ACL for the Web services port to determine if any entries are already using the relevant host name and port by typing the following command:

    CopyCode image Copy Code
    httpcfg query urlacl

    In the data that is returned to the prompt, '+' (plus sign) represents localhost.

    Note Note

    If you have previously configured Microsoft Dynamics NAV Web services for delegation using the instructions in How to: Configure Web Services with Delegation, you will have also previously configured an ACL for the http URL. We recommend deleting that ACL and replacing it with one for the https URL as described in the following steps because Web services clients could otherwise connect to Microsoft Dynamics NAV without using SSL.

  3. Delete any entries that use your host name and Web service port, such as:

    CopyCode image Copy Code
    httpcfg delete urlacl –u http://+:7047/DynamicsNAV/

  4. Register the port with https:

    CopyCode image Copy Code
    httpcfg set urlacl -u https://+:7047/DynamicsNAV/ -a D:^(A;^;GX^;^;^;<security identifier>)

    Replace <security identifier> with the actual security-identifier attribute (SID) for the account. A security identifier is a unique value of variable length used to identify a user or group account. For more information, see Security Identifiers.

  5. Requery the ACL as you did in step 2 to verify that your port has been registered.

To configure the port to use the SSL certificate

  1. At the command prompt, type the following command to view the current port configuration:

    CopyCode image Copy Code
    httpcfg query ssl

  2. If SSL is already configured on the address and port that you want to use, where 0.0.0.0 indicates all IP addresses, then delete it using the following command and substitute your IP and port number:

    CopyCode image Copy Code
    httpcfg delete ssl –i 0.0.0.0:7047

  3. Associate the certificate with your port, using the IP address, port number, and thumbprint that you pasted to Notepad:

    CopyCode image Copy Code
    httpcfg set ssl -i <ip address>:<port> -h <thumbprint>

Expand image Verifying the Configuration

You should now be able to use Web services that are encrypted with SSL. To verify this, type the following URL in the address bar for your browser.

https://localhost:7047/DynamicsNAV/WS/services

The page lists any Web services that have been published.

Expand image Next Steps

You can now try any other walkthroughs in this section of the online Help. The only change that is required for using these walkthrough with SSL is that you use "https" instead of "http" in your URLs.

Expand image See Also

Tasks

How To: Set Up Delegation

Concepts

Security in the RoleTailored Environment


Extending the RoleTailored Client Using Control Add-ins in Microsoft Dynamics 2009 SP1

Extending the RoleTailored Client Using Control Add-ins in Microsoft Dynamics 2009 SP1
See Also

In Microsoft Dynamics NAV 2009 SP1, RoleTailored client control add-ins add custom functionality to Role Centers and pages. The following sections provide an overview of the documentation available for developing and using control add-ins.

Getting an Overview of Control Add-ins

To | See
Get a general overview control add-ins and where they fit in the Microsoft Dynamics NAV 2009 architecture. | RoleTailored Client Control Add-in Overview

Developing Control Add-ins

To See

Get a general overview about developing control add-ins, including design considerations.

Developing RoleTailored Client Control Add-ins

Learn how to create a control add-in.

How to: Create a RoleTailored Client Control Add-in

Learn how control add-ins bind with data in the Microsoft Dynamics NAV database.

Binding a RoleTailored Client Control Add-in to the Database

Learn how control add-ins use events to call C/AL triggers on a page.

Calling C/AL Triggers from a RoleTailored Client Control Add-in

Learn about the client extensibility API that you use to create control add-ins.

Client Extensibility API Overview

Note Note

For more information about the API, see the Client Extensibility Reference for Microsoft Dynamics NAV in the Reference section.

Follow a walkthrough that leads you from the development of a simple control add-in through its implementation on a page

Walkthrough: Creating and Using a RoleTailored Client Control Add-in

Using RoleTailored Client Control Add-ins on Pages

To | See
Get a general overview about the using control add-ins on RoleTailored client pages. | Installing and Configuring RoleTailored Client Control Add-ins on Pages
Learn how to install control add-ins on computers running the RoleTailored client. | How to: Install a RoleTailored Client Control Add-in Assembly
Learn how to register a control add-in in the Microsoft Dynamics NAV database so it is available for use on pages. | How to: Register a RoleTailored Client Control Add-in
Learn how to use a control add-in on a page. | How to: Set up a RoleTailored Client Control Add-in on a Page
Follow a walkthrough that leads you from the development of a simple control add-in through its implementation on a page | Walkthrough: Creating and Using a RoleTailored Client Control Add-in

See Also

Tasks

How to: Determine the Public Key Token of the RoleTailored Client Control Add-in

Concepts

Creating and Maintaining Pages

Other Resources

Tour of the RoleTailored Client for Developers


RoleTailored Client Control Add-in Overview

RoleTailored Client Control Add-in Overview

With Microsoft Dynamics NAV 2009 SP1, you use RoleTailored client control add-ins to extend the RoleTailored client with custom functionality. A control add-in is a custom control, or visual element, for displaying and modifying data on RoleTailored client pages. The following figure illustrates a control add-in example that displays a gauge control on a page.

Control add-ins are delivered as Microsoft .NET Framework–based assemblies that you install on computers running the RoleTailored client. You register the control add-in in Microsoft Dynamics NAV Server, and you can then use the control add-in with RoleTailored client pages. For more information, see Installing and Configuring RoleTailored Client Control Add-ins on Pages.

You can use Microsoft Visual Studio to create your own control add-ins. For more information, see Developing RoleTailored Client Control Add-ins.

RoleTailored Client Control Add-in Model

The following figure illustrates the RoleTailored client within the Microsoft Dynamics NAV 2009 architecture.

RoleTailored client control add-in model

You install control add-in assemblies on the computer running the RoleTailored client, not the computer running Microsoft Dynamics NAV Server. Unlike pages that are instantiated by C/AL code, control add-ins are instantiated using metadata that is found in the Microsoft Dynamics NAV database.

See Also

Concepts

Installing and Configuring RoleTailored Client Control Add-ins on Pages
Developing RoleTailored Client Control Add-ins


Developing RoleTailored Client Control Add-ins

Developing RoleTailored Client Control Add-ins

Microsoft Dynamics NAV 2009 SP1 includes the client extensibility application programming interface (API) for creating RoleTailored client control add-ins. The client extensibility API is provided in the Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly, which is installed with the RoleTailored client. You develop control add-ins using Microsoft Visual Studio and distribute them as Microsoft .NET Framework–based assemblies for deployment to computers running the RoleTailored client.

Design Considerations When Developing Control Add-ins

This section includes things to consider when developing control add-ins.

Using a Control Add-in on Pages

  • You apply control add-ins on field controls of RoleTailored client pages.

  • You can apply control add-ins on more than one field control on a page.

  • You can use control add-ins on all page types except a RoleCenter page type.

    Note Note

    To include a control add-in on a Role Center, you apply the control add-in on a page that is assigned to a part of the Role Center.

  • You can use control add-ins on pages that are included in parts and FactBoxes of other pages.

  • You can design the user interface of the control add-in to fill the page part area entirely or partially.

  • You cannot use control add-ins on the following areas:

    • On a field under a repeater control, which is used display data in a list, such as in a list place

    • Action Pane

    • Command bar

    • Filter pane

Binding a Control Add-in to the Database

A control add-in can bind with data in the Microsoft Dynamics NAV database, which allows you to create control add-ins that can display and update data in the database. For more information, see Binding a RoleTailored Client Control Add-in to the Database.

Calling C/AL Triggers on a Page

By implementing events, a control add-in can call the OnControlAddin trigger of page field that is applied with the control add-in. For more information, see Calling C/AL Triggers from a RoleTailored Client Control Add-in.

See Also

Tasks

How to: Create a RoleTailored Client Control Add-in

Concepts

Client Extensibility API Overview
Binding a RoleTailored Client Control Add-in to the Database
Calling C/AL Triggers from a RoleTailored Client Control Add-in
Installing and Configuring RoleTailored Client Control Add-ins on Pages
RoleTailored Client Control Add-in Overview


Client Extensibility API Overview

Client Extensibility API Overview

Microsoft Dynamics NAV 2009 SP1 includes the client extensibility API, which defines the model for creating RoleTailored client control add-ins. The client extensibility API uses .NET interfaces as the binding mechanism between the control add-ins on a page and the Microsoft Dynamics NAV framework. When you develop a control add-in, you can choose among various interfaces and base classes to implement based the control add-in requirements.

Control Add-in Definition Interfaces

You can develop a control add-in to bind with data in the Microsoft Dynamics NAV database and raise events that call the OnControlAddin trigger on a page field control that is applied with the control add-in. For more information, see Binding a RoleTailored Client Control Add-in to the Database and Calling C/AL Triggers from a RoleTailored Client Control Add-in.

To support data binding and events in a control add-in, you must implement one of the control add-in definition interfaces that are described in the following table.

Interface Use

Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition

Base interface that binds the control add-in with System.String or System.Object data types as defined by the T parameter.

Displays text strings or binary data from the Microsoft Dynamics NAV database.

Note Note

The Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase base class implements this interface with a System.String data type.

Microsoft.Dynamics.Framework.UI.Extensibility.IEventControlAddInDefinition

Base interface that defines a Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInEventHandler event.

Uses events to call the OnControlAddin Trigger of a page field control.

Note Note

The Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase class implements this interface.

Microsoft.Dynamics.Framework.UI.Extensibility.IObjectControlAddInDefinition

Base interface that binds the control add-in with a System.Object data type and raises a Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInEventHandler event.

Displays binary data from a Microsoft Dynamics NAV database and uses events to call the OnControlAddin trigger of a page field control.

Microsoft.Dynamics.Framework.UI.Extensibility.IStringControlAddInDefinition

Base interface that binds the control add-in with a System.String data type and provides a control add-in definition interface that raises a Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInEventHandler event.

Displays text strings from Microsoft Dynamics NAV Server and uses events to call the OnControlAddin trigger of a page field control.

Note Note

The Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase class implements this interface.

Control Add-in Base Classes

To develop control add-ins that target Windows Forms–based displays, the client extensibility API includes the Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.IWinFormsControlAddIn interface. You can implement this interface explicitly and override its members, or you can implement an available abstract base class that implements the interface for you. Use the following table to decide which base class to use:

Base class Use

Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.WinFormsControlAddInBase

Base class that targets Windows Forms displays with a control add-in.

You can use this base class for any control add-in with an appropriate control add-in definition interface.

Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase

Base class that implements the Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition and Microsoft.Dynamics.Framework.UI.Extensibility.IEventControlAddInDefinition

interfaces.

This base class overrides the Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition.Value property to bind the control add-in to a System.String data type in Microsoft Dynamics NAV Server. It also defines the Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase.RaiseControlAddInEvent(System.Int32,System.String) method for raising events.

You can use this base class for a control add-in that displays text strings from a simple text box control and supports events that call the C/AL trigger on the page.

See Also

Tasks

How to: Create a RoleTailored Client Control Add-in

Concepts

Developing RoleTailored Client Control Add-ins
Binding a RoleTailored Client Control Add-in to the Database
Calling C/AL Triggers from a RoleTailored Client Control Add-in
Installing and Configuring RoleTailored Client Control Add-ins on Pages
RoleTailored Client Control Add-in Overview


Binding a RoleTailored Client Control Add-in to the Database

Binding a RoleTailored Client Control Add-in to the Database

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Similar to other field controls on a page, a RoleTailored client control add-in can bind with data in the Microsoft Dynamics NAV database. This allows you to create control add-ins that can display and update data in the database. Data binding is accomplished through Microsoft Dynamics NAV Server with the SourceExpr Property of the field control that is applied with the control add-in as illustrated in the following figure.

RoleTailored client control add-in data binding

The control add-in must implement the Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition interface that exposes the Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition.Value property. When a control add-in is instantiated on a page, the SourceExpr property value is passed to the control add-in Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition.Value property.

Note Note

The SourceExpr property value can be passed to Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition.Value property multiple times while a page is open, depending on application code or state in the RoleTailored client.

The SourceExpr property can be a field in a database table or a C/AL global variable. Control add-ins support text string (System.String) and object (Object) data types.

For more information about implementing the Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition interface, see How to: Create a RoleTailored Client Control Add-in.

For more information about setting the SourceExpr property for a control add-in, see How to: Set up a RoleTailored Client Control Add-in on a Page.

See Also

Tasks

How to: Create a RoleTailored Client Control Add-in

Concepts

Developing RoleTailored Client Control Add-ins
Client Extensibility API Overview
Calling C/AL Triggers from a RoleTailored Client Control Add-in
Installing and Configuring RoleTailored Client Control Add-ins on Pages
RoleTailored Client Control Add-in Overview


Calling C/AL Triggers from a RoleTailored Client Control Add-in

Calling C/AL Triggers from a RoleTailored Client Control Add-in
See Also

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

RoleTailored client pages include an OnControlAddin Trigger on field controls that control add-ins can invoke to run C/AL code. To invoke the OnControlAddIn trigger, a control add-in sends an event to Microsoft Dynamics NAV Server as illustrated in the following figure.

RoleTailored client control add-in events

An example of an event is when a user clicks a button in the control add-in display on the page. To program events in a control add-in, you implement the Microsoft.Dynamics.Framework.UI.Extensibility.IEventControlAddInDefinition interface.

An event sends data to Microsoft Dynamics NAV Server in two attributes: Index and Data. The Index attribute value is an integer data type. The Data attribute value is a text string data type. You add C/AL code to the OnControlAddIn trigger to process the data.

Note Note

The Data attribute on the OnControlAddIn trigger supports both Text and BigText data types from Microsoft Dynamics NAV Server. The data type is determined by the SourceExpr property of the field control that is applied with the control add-in. If the SourceExpr property value is BigText, then the Data attribute is BigText. Otherwise, the Data attribute is Text[1024]. For more information on data types, see C/AL Functions.

For more information about creating events in a control add-in, see How to: Create a RoleTailored Client Control Add-in.

For more information about setting up the OnControlAddin trigger on a page, see How to: Set up a RoleTailored Client Control Add-in on a Page.

See Also

Tasks

How to: Create a RoleTailored Client Control Add-in

Concepts

Developing RoleTailored Client Control Add-ins
Client Extensibility API Overview
Binding a RoleTailored Client Control Add-in to the Database
Installing and Configuring RoleTailored Client Control Add-ins on Pages
RoleTailored Client Control Add-in Overview


How to: Create a RoleTailored Client Control Add-in

How to: Create a RoleTailored Client Control Add-in
See Also Example

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

You develop RoleTailored client control add-ins using the API that is defined in the Microsoft.Dynamics.Framework.UI.Extensibility assembly. A control add-in is defined as a class in a Visual C# solution. You can include more than one control add-in a single solution. When you are done developing a control add-in, you build and sign and assembly before you install it on the computer running the RoleTailored client.

To create a control add-in, you need the following prerequisites:

  • Microsoft Visual Studio 2005, or Microsoft Visual Studio 2008, or Visual C# 2008 Express Edition.

  • Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly.

    The assembly is installed with the RoleTailored client. By default, the path to the assembly is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client. For more information, see Install and Configure Microsoft Dynamics NAV 2009 SP1.

  • Windows Forms library (System.Windows.Forms.dll).

To create the RoleTailored client control add-in

  1. In Visual Studio, create a Visual C# project type using the Class Library template.

  2. In the project, add references to the following assemblies:

    • Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly

      By default, the path to the assembly is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client. This reference is required for all control add-ins.

    • System.Windows.Forms

      Contains classes for creating user interfaces for Windows-based applications.

    Add additional references as required.

  3. Open the class.cs file and add the following using directives:

    C# CopyCode image Copy Code
    using Microsoft.Dynamics.Framework.UI.Extensibility;
using Microsoft.Dynamics.Framework.UI.Extensibility.WinForms;
using System.Windows.Forms;

    Add additional references as required.

  4. Declare a class for the control add-in that uses the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute. Derive the class from an abstract base class and implement the control add-in definition interface, as shown in the following examples:

    C# CopyCode image Copy Code
    [ControlAddInExport("MyCompany.MyProduct.MyAddin")]
public class MyFieldPopupAddin : WinFormControlAddInBase, IObjectControlAddinDefinition

    CopyCode image Copy Code
    [ControlAddInExport("MyCompany.MyProduct.MyAddin")]
public class MyFieldPopupAddin : StringControlAddInBase

    For information about the base classes and interfaces, see Client Extensibility API Overview.

    The Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute declares the class in the assembly to be a control add-in that is identified by its Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute.Name property, which in this case is MyCompany.MyProduct.MyAddin. Because an assembly can contain more than one control add-in, the RoleTailored client uses the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute to differentiate each control add-in that is found in an assembly. The Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute.Name is used to register the control add-in in Microsoft Dynamics NAV Server. For more information, see How to: Register a RoleTailored Client Control Add-in.

  5. Implement the abstract base method Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.WinFormsControlAddInBase.CreateControl and add code that defines the control add-in.

    C# CopyCode image Copy Code
    protected override Control CreateControl()
       {
           /// Include control add-in code here.
       }

  6. Add code to override additional base class members as required for your control add-in.

    For example, a field control on a RoleTailored page can have a caption. If you do not want a caption, then override the Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.WinFormsControlAddInBase.AllowCaptionControl property and return false (the default value is true) as follows:

    C# CopyCode image Copy Code
    public override bool AllowCaptionControl
{
get
{
 return false;
}

    The caption will span the caption column and the data column of the page.

  7. To bind the control add-in to data in the Microsoft Dynamics NAV database, add the following code that gets or sets the Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition.Value property.

    C# CopyCode image Copy Code
           public object Value
        {
            get
            {
                throw new NotImplementedException();
            }
            set
            {
                throw new NotImplementedException();
            }
        }
    Note Note

    The Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase class already overrides the Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition.Value property to transfer data between the control add-in and the Microsoft Dynamics NAV database.

    For more information, see Binding a RoleTailored Client Control Add-in to the Database.

  8. To define events that call the OnControlAddin C/AL trigger of a page field control, add the following code to declare an event handler.

    C# CopyCode image Copy Code
       public event ControlAddInEventHandler ControlAddIn;

    Add code to raise the event where appropriate.

    For more information, see Calling C/AL Triggers from a RoleTailored Client Control Add-in.

  9. Build and sign the solution.

Signing an Assembly That Contains a Control Add-in

To use an assembly that contains a control add-in with the RoleTailored client, it must be signed. Signing gives the assembly a public token key, which is a unique identity that is used to ensure that the control add-in runs code from a trusted assembly. When you register a control add-in in Microsoft Dynamics NAV Server, you provide the public token key. At run time, the RoleTailored client uses the public token key to load the appropriate control add-in.

Assemblies are signed with a key file that contains the public key token and an optional password. You can sign an assembly that contains a control add-in by creating a new key file or using an existing one. For more information about signing assemblies, see How to: Sign Assemblies and Strong-Name Signing for Managed Applications.

To sign the RoleTailored client add-in assembly

  1. Open the project's properties.

  2. On the Properties window, click the Signing tab.

  3. Select the Sign the assembly check box.

  4. In the Choose a strong name key file box, select <New…> to create a new key file or <Browse…> to use an existing key file.

  5. Click OK.

For information about determining the public token key, see How to: Determine the Public Key Token of the RoleTailored Client Control Add-in.

Example

The following code illustrates a control add-in that implements the Microsoft digital ink control on a RoleTailored client page field. For example, you could use this control add-in on a sales order page to allow customers to sign their sales orders with a Tablet PC. The control add-in is designed to bind with a table field in the Microsoft Dynamics NAV database to store and retrieve signatures. Because the signatures are transferred as binary data, the example implements the Microsoft.Dynamics.Framework.UI.Extensibility.IObjectControlAddInDefinition interface.
C# CopyCode image Copy Code
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.Ink;
using System.Drawing;
using Microsoft.Dynamics.Framework.UI.Extensibility;
using Microsoft.Dynamics.Framework.UI.Extensibility.WinForms;
using System.Windows.Forms;

namespace NavInkControl
{
    [ControlAddInExport("MyCompany.MyProduct.MyNavInkControlAddin")]
    public class NavInkContol : WinFormsControlAddInBase, IObjectControlAddInDefinition
    {
        InkPicture _inkControl;
        private bool _loaded = false;

        /// Creates the control for displaying and adding signatures.
        protected override Control CreateControl()
        {
            _inkControl = new InkPicture();
            _inkControl.BorderStyle = System.Windows.Forms.BorderStyle.Fixed3D;
            _inkControl.MinimumSize = new Size(40, 50);
            _inkControl.MaximumSize = new Size(Int16.MaxValue, 100);

            return _inkControl;
        }

        #region IObjectControlAddInDefinition Members

        public event ControlAddInEventHandler ControlAddIn;

        /// Gets a value indicating whether the Value property instance has changed. true if this instance has changed its value; otherwise, false.
        public bool HasValueChanged
        {
            get { return _inkControl.Ink.Dirty; }
        }

        /// Gets or sets the value.
        public object Value
        {
            get
            {
                return this._inkControl.Ink.Save();
            }
            set
            {
                if (value is byte[])
                {
                    byte[] data = (byte[])value;

                /// Specifies that the data loads only once so that data cannot load while the the user is drawing.
                    if (data != null && !this._loaded)
                    {
                        this._inkControl.Ink.Load(data);
                        this._loaded = true;
                    }
                }
            }
        }

        #endregion
    }

See Also

Tasks

Walkthrough: Creating and Using a RoleTailored Client Control Add-in

Concepts

Developing RoleTailored Client Control Add-ins
Client Extensibility API Overview
Binding a RoleTailored Client Control Add-in to the Database
Calling C/AL Triggers from a RoleTailored Client Control Add-in
Installing and Configuring RoleTailored Client Control Add-ins on Pages
RoleTailored Client Control Add-in Overview


How to: Determine the Public Key Token of the RoleTailored Client Control Add-in

How to: Determine the Public Key Token of the RoleTailored Client Control Add-in
See Also

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

To use a RoleTailored client control add-in on a RoleTailored client page, you must register the assembly that contains the control add-in in the Client Add-in table of the Microsoft Dynamics NAV 2009 database. To register an assembly, you provide the assembly's public key token. The public key token is a unique 16-character key that is given to the assembly when it is built and signed in Microsoft Visual Studio. To determine the public token key, you can run the Strong Name tool (sn.exe) on the assembly. The sn.exe is available with the Microsoft .NET Framework SDK. For more information about signing assemblies, see Strong Name or How to: Create a RoleTailored Client Control Add-in.

To determine the add-in's public key token

  1. Locate the sn.exe file.

    The default folder for the Microsoft .NET Framework SDK is C:\program files\microsoft sdks\windows\v7.0\Bin.

  2. At the command prompt, change to the directory that contains the sn.exe utility.

  3. Type the following command:

    CopyCode image Copy Code
    sn.exe -T <assembly>

    Replace <assembly> with the add-in assembly's path and file name, such as Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-ins\MyCompany.MyProduct.RtcAddins.dll.

  4. Press ENTER and note the public token key that is displayed.

See Also

Tasks

How to: Create a RoleTailored Client Control Add-in
How to: Install a RoleTailored Client Control Add-in Assembly

Concepts

RoleTailored Client Control Add-in Overview
Developing RoleTailored Client Control Add-ins
Installing and Configuring RoleTailored Client Control Add-ins on Pages


Installing and Configuring RoleTailored Client Control Add-ins on Pages

Installing and Configuring RoleTailored Client Control Add-ins on Pages
See Also

In Microsoft Dynamics NAV 2009 SP1, RoleTailored client control add-ins add custom controls, or visual elements, on RoleTailored client page fields for displaying and editing data. When a control add-in is developed, it is compiled into a .NET Framework–based assembly, which is .dll file. To use a control add-in on RoleTailored client pages, you must install and configure the control add-in assembly in the RoleTailored client environment, which is divided between two tiers: RoleTailored client and Microsoft Dynamics NAV 2009 SQL server database.

RoleTailored client control add-in installation

The following table outlines the tasks that you must perform on each tier:

Tier Tasks For more information, see

RoleTailored client computer

Install the control add-in assemblies.

How to: Install a RoleTailored Client Control Add-in Assembly

SQL database

Use the Classic client to:

  1. Register the control add-ins that are found in the assemblies in the Client Add-in table.

  2. Set up control add-ins on pages.

How to: Register a RoleTailored Client Control Add-in

How to: Set up a RoleTailored Client Control Add-in on a Page

See Also

Tasks

Walkthrough: Creating and Using a RoleTailored Client Control Add-in

Concepts

Developing RoleTailored Client Control Add-ins
RoleTailored Client Control Add-in Overview
RoleTailored Architecture


How to: Install a RoleTailored Client Control Add-in Assembly

How to: Install a RoleTailored Client Control Add-in Assembly
See Also

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

RoleTailored client control add-ins are provided in one or more Microsoft Framework .NET–based assemblies, which are .dll files. The assemblies that contain RoleTailored client add-ins are not installed with the default RoleTailored client installation. For any RoleTailored client instance that will use the control add-ins, you must manually install the assemblies.

Note Note

Control add-ins must also be registered in the Client Add-in table of Microsoft Dynamics NAV database and set up on pages. For more information, see How to: Register a RoleTailored Client Control Add-in and How to: Set up a RoleTailored Client Control Add-in on a Page.

To install RoleTailored client add-in assemblies

  1. If not already done, install the RoleTailored client on the computer.

    For more information, see Install and Configure Microsoft Dynamics NAV 2009 SP1.

  2. On the computer running the RoleTailored client, copy the assemblies that contain the control add-ins to the Add-ins folder of the RoleTailored client installation.

    By default, the path to this folder is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-ins.

    Note Note

    You can also place assemblies in a subfolder of the Add-ins folder. This can be useful when you have multiple assemblies and dependencies.

See Also

Tasks

How to: Set up a RoleTailored Client Control Add-in on a Page
How to: Install a RoleTailored Client Control Add-in Assembly
Walkthrough: Creating and Using a RoleTailored Client Control Add-in

Concepts

Installing and Configuring RoleTailored Client Control Add-ins on Pages
Developing RoleTailored Client Control Add-ins
Installing and Configuring RoleTailored Client Control Add-ins on Pages
RoleTailored Client Control Add-in Overview


How to: Register a RoleTailored Client Control Add-in

How to: Register a RoleTailored Client Control Add-in

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

A RoleTailored client control add-in is delivered as a Microsoft .NET Framework–based assembly, which is a .dll file. An assembly for RoleTailored client add-ins can contain more than one control add-in where each control add-in has a unique name. Before you can use a control add-in on pages, you use the Classic client to register it in the Client Add-in table of your Microsoft Dynamics NAV database.

To register a control add-in, provide the following information:

Information Description

Control add-in name

The name is defined in the assembly's source code by the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute value for control add-in class definition, as shown in the following example code snippet:

CopyCode image Copy Code
[ControlAddInExport("MyCompany.MyProduct.FieldPopupAddin")]
public class MyFieldPopupAddin : StringControlAddInBase, IStringControlAddInDefinition

In this example, the control add-in name is MyCompany.MyProduct.FieldPopupAddin. For more information, see How to: Create a RoleTailored Client Control Add-in.

Public key token

The public key token is a 16-character key that is given to the assembly when it is built and signed in Microsoft Visual Studio. To determine the public token key, run the Microsoft .NET Strong Name Utility (sn.exe) on the assembly. For more information, see How to: Determine the Public Key Token of the RoleTailored Client Control Add-in and Strong-Named Signing.

To register a RoleTailored client control add-in

  1. Open the Classic client.

  2. On the Tools menu, click Object Designer.

  3. Click Tables, and then locate the table with ID 2000000069 and name Client Add-in.

  4. Click the table, and then click Run.

  5. On a blank line in the Client Add-in table, fill in the Control Add-In Name and Public Key Token fields.

  6. Close the Client Add-in table.

See Also

Tasks

How to: Set up a RoleTailored Client Control Add-in on a Page
How to: Install a RoleTailored Client Control Add-in Assembly
How to: Determine the Public Key Token of the RoleTailored Client Control Add-in
Walkthrough: Creating and Using a RoleTailored Client Control Add-in

Concepts

Installing and Configuring RoleTailored Client Control Add-ins on Pages
Developing RoleTailored Client Control Add-ins
RoleTailored Client Control Add-in Overview


How to: Set up a RoleTailored Client Control Add-in on a Page

How to: Set up a RoleTailored Client Control Add-in on a Page
See Also

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

After you have registered a RoleTailored client control add-in, you can use it on RoleTailored client pages. To use a control add-in on a page, you add it to a field control. Depending on the design of the control add-in, you may also need to do the following steps:

  • Bind the control add-in field to a data source.

    Control add-ins can use data from a field in the table that is associated with the page or from a C/AL global variable. For more information, see Binding a RoleTailored Client Control Add-in to the Database.

  • Modify the control add-in C/AL trigger to process data that is sent from the RoleTailored client. For more information, see Modifying the RoleTailored Client Control Add-in Event Trigger.

Preparing to Set Up the Control Add-in

To prepare for setting up the control add-in

  1. If the control add-in uses data from a table that does not exist, then create the table.

    For more information, see How to: Create a Table.

  2. If the page to which you want to add the control add-in does not exist, then create the page. As appropriate, associate the page with the table that you created in step 1.

    For more information, see How to: Create a Page.

Setting Up a Control Add-in on a Page Field

To set the ControlAddIn property on the field

  1. Open the Classic client.

  2. On the Tools menu, click Object Designer, and then click Page.

  3. Select the page, and then click Design.

  4. In Page Designer, add a field control for the control add-in or use an existing field control.

  5. Select the field, and then on the View menu, click Properties.

  6. In the ControlAddIn property value, click the lookup button.

  7. In the Client Add-in window, select the control add-in from the Client Add-in window, and then click OK.

    For more information, see the ControlAddin Property.

  8. To bind the field to data in a table field or C/AL global variable, set the SourceExpr property.

    Note Note

    If the SourceExpr property is set to a C/AL global variable, then in the C/AL code, add code to the OnAfterGetRecord trigger to populate the global variable. For more information, see OnAfterGetRecord Trigger.

  9. Close the Properties window.

Modifying the RoleTailored Client Control Add-in Event Trigger

When invoked on a page, a control add-in can raise an event that sends data to Microsoft Dynamics NAV Server. In the C/AL code for the page, the event calls the OnControlAddIn trigger of the field control that is applied with the control add-in. To process the event data, you add C/AL code to the OnControlAddIn trigger. For more information, see Calling C/AL Triggers from a RoleTailored Client Control Add-in.

To add C/AL code to the control add-in event trigger

  1. On the View menu, click C/AL Code.

  2. In the C/AL Editor, locate the following field control trigger:

    CopyCode image Copy Code
    Fieldname - OnControlAddIn(Index : Integer;Data : Text[1024])

    Fieldname is the name of the field control that is applied with the control add-in.

    Note Note

    If the data type of the field's SourceExpr property is BigText, then the Data attribute is BigText instead of Text[1024].

  3. Add the C/AL code to the trigger.

  4. Close the C/AL Editor.

  5. On the File menu, click Save, select Compiled, and then click OK.

See Also

Tasks

How to: Install a RoleTailored Client Control Add-in Assembly
How to: Register a RoleTailored Client Control Add-in
How to: Install a RoleTailored Client Control Add-in Assembly
Walkthrough: Creating and Using a RoleTailored Client Control Add-in

Reference

ControlAddin Property

Concepts

RoleTailored Client Control Add-in Overview
Installing and Configuring RoleTailored Client Control Add-ins on Pages
Developing RoleTailored Client Control Add-ins


Walkthrough: Creating and Using a RoleTailored Client Control Add-in

Walkthrough: Creating and Using a RoleTailored Client Control Add-in
See Also
CollapseAll image

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

The following walkthrough demonstrates how to develop a RoleTailored client add-in and use it on a RoleTailored client page. Add-ins are Microsoft .NET assemblies that allow you to add custom functionality to the RoleTailored client. An application programming interface (API) lets you develop add-ins without having to access the Microsoft Dynamics NAV 2009 source code.

In a typical business scenario, .NET developers create add-ins using Microsoft Visual Studio Express, Visual Studio 2005, or Visual Studio 2008. Implementers of Microsoft Dynamics NAV solutions then use the add-ins on RoleTailored client pages.

Expand image About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating an add-in with Visual Studio 2005 or Visual Studio 2008.

  • Copying the add-in assembly to the computer running the RoleTailored client.

  • Registering the add-in in Microsoft Dynamics NAV.

  • Setting Up the add-in on a page.

Roles

This walkthrough demonstrates tasks performed by the following user roles:

  • Microsoft .NET developer.

  • Microsoft Dynamics NAV developer and IT Pro.

Prerequisites

To complete this walkthrough, you need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements met. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

  • Microsoft Visual Studio Express, 2005 or 2008.

  • Microsoft .NET Strong Name Utility (sn.exe). This is included with Visual Studio 2005 or Visual Studio 2008 SDKs.

  • Experience with Visual Studio 2005 or Visual Studio 2008.

Expand image Story

Simon is a software developer working for CRONUS International Ltd. He has been told that users of the RoleTailored client would like a way to see the entire content of page fields when the content extends beyond the field size. He decides to create an add-in that can be applied on a field that allows the user to double-click the field to display its full content. Fields applied with add-in are displayed as blue. When the user double-clicks the field, a popup window opens that shows the field's content. The following figure illustrates the add-in on a Customer Card page.

Add-in that opens popup window on Card page field

Expand image Creating an Add-in with Visual Studio 2005 or 2008

Microsoft Dynamics NAV 2009 includes the Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly that defines the model for creating RoleTailored client add-ins. The API provides the binding mechanism between the RoleTailored client add-in and the Microsoft Dynamics NAV 2009 framework.

To create the add-in

  1. In Visual Studio Express, Visual Studio 2005 or Visual Studio 2008, create a Visual C# project type using the Class Library template.

    Name the solution MyCompany.MyProduct.RtcAddins.

  2. In the project, add references to the following assemblies:

    • Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly

      By default, the path to the assembly is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client. This reference is required for all RoleTailored client add-ins.

    • System.Windows.Forms

      Contains classes for creating user interfaces for Windows-based applications.

    • System.Drawing

      Provides access to basic graphics functionality.

  3. Open the Class1.cs file and add the following using directives:

    C# CopyCode image Copy Code
    using Microsoft.Dynamics.Framework.UI.Extensibility;
using Microsoft.Dynamics.Framework.UI.Extensibility.WinForms;
using System.Windows.Forms;
using System.Drawing;

  4. Declare a new class for the add-in that uses the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute and derives from the Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase class and Microsoft.Dynamics.Framework.UI.Extensibility.IStringControlAddInDefinition interface as follows:

    C# CopyCode image Copy Code
    [ControlAddInExport("MyCompany.MyProduct.FieldPopupAddin")]
public class MyFieldPopupAddin : StringControlAddInBase

    The Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute declares the class in the assembly to be a control add-in that is identified by its Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute.Name property, which in this case is MyCompany.MyProduct.FieldPopupAddin. Because an assembly can contain more than one control add-in, the RoleTailored client uses the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute to differentiate each control add-in that is found an assembly.

    Note Note

    You will use the name MyCompany.MyProduct.FieldPopupAddin later in the walkthrough when you register the add-in in Microsoft Dynamics NAV 2009. When naming the control add-in, it is good practice to follow the .NET Framework naming convention for classes, which is CompanyName.ProductName.ControlName.

    The Microsoft.Dynamics.Framework.UI.Extensibility.IStringControlAddInDefinition interface determines how data transfers to and from the add-in and how events are raised to call triggers on Microsoft Dynamics NAV Server.

  5. Implement the abstract Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.WinFormsControlAddInBase.CreateControl method and add the code that defines the add-in functionality as follows:

    C# CopyCode image Copy Code
    /// Defines the text box control.
{
    protected override Control CreateControl()
    {
        TextBox control = new TextBox();

        control.MinimumSize = new Size(50, 0);
        control.MaximumSize = new Size(500, Int32.MaxValue);

        control.BackColor = Color.LightBlue;
        control.Font = new Font("Tahoma", 9, FontStyle.Bold);
        control.DoubleClick += control_DoubleClick;

        return control;
    }
/// Raises an event when the user double-clicks the text box.
    private void control_DoubleClick(object sender, EventArgs e)
    {
        int index = 0;
        string data = this.Control.Text;
        this.RaiseControlAddInEvent(index, data);

    }
}
    Note Note

    If you want to create an add-in that spans both the caption column and the data column of the page, override the Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.IWinFormsControlAddIn.AllowCaptionControl property and return false (default value is true).

  6. Sign the add-in assembly. An assembly must be signed to be used in the RoleTailored client. Open the project's properties.

  7. On the Properties window, click Signing, and then select the Sign the assembly checkbox.

  8. In the Choose a strong name key file box, select <New…>.

  9. In the Key file name box, type RtcAddins.

    You can choose whether to use a password. For more information, see Strong-Name Signing for Managed Applications.

  10. Click OK.

  11. Build the solution.

Expand image Copying the Add-in Assembly to the Computer Running the RoleTailored Client

After you build the add-in, you copy the output assembly file to the computer running the RoleTailored client.

To copy the add-in assembly to the RoleTailored client

  1. On the development computer, locate the add-in assembly file in the add-in project's output folder.

    By default, this folder is C:\My Documents\Visual Studio\Projects\[Addin Project]\bin\Debug.

  2. On the computer running the RoleTailored client, copy the assembly to the RoleTailored client\Add-ins folder in the Microsoft Dynamics NAV 2009 installation folder.

    By default, the path to this folder is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-ins.

Expand image Registering the Add-in in Microsoft Dynamics NAV

To register an add-in, you include it in the Client Add-in table in Microsoft Dynamics NAV. To include an add-in in the table, you must provide the following information:

  • Add-in name

    The add-in name is determined by the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute value of add-in class definition that you specified when creating the control add-in. The name in this walkthrough is MyCompany.MyProduct.FieldPopupAddin, as shown in the following code snippet from interface definition:

    C# CopyCode image Copy Code
    [ControlAddInExport("MyCompany.MyProduct.FieldPopupAddin")]
public class MyFieldPopupAddin : StringControlAddInBase

  • Public key token

    This is a 16-character key that is given to the assembly when it is signed and built in Visual Studio. To determine the public token key, run the Microsoft .NET Strong Name Utility (sn.exe) on the assembly. The sn.exe utility is available with the Visual Studio 2005 and Visual Studio 2008 SDKs.

To determine the add-in's public key token

  1. At a command prompt, change to the directory that contains the sn.exe utility.

    For example, the default directory for Microsoft Visual Studio 2008 is C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin.

  2. Type the following command:

    CopyCode image Copy Code
    sn.exe -T <assembly>

    Replace <assembly> with the add-in assembly's path and file name, such as Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-ins\MyCompany.MyProduct.RtcAddins.dll.

  3. Press ENTER and note the public token key that is displayed.

To include the add-in in the Client Add-in table

  1. Open the Classic client.

  2. On the Tools menu, click Object Designer.

  3. Click Tables, and then locate the table with ID 2000000069 and name Client Add-in.

  4. Click the table, and then click Run.

  5. On a blank line in the Client Add-in table, fill out the Control Add-In Name and Public Key Token fields.

    In this walkthrough, the name is MyCompany.MyProduct.FieldPopupAddin.

  6. Close the Client Add-in table.

Expand image Setting Up the Add-in on a Page

In this section, you will modify the Customer Card page to use the new add-in on the name field. This involves the following tasks:

  • Setting the ControlAddin Property of the field to the add-in.

  • Setting the OnControlAddin Trigger trigger.

    In the C/AL Editor, you set the trigger that is called when a user double-clicks the field to open a popup window. When a field is double-clicked, the add-in raises the Microsoft.Dynamics.Framework.UI.Extensibility.IEventControlAddInDefinition.ControlAddIn event which in turn calls the trigger.

To set the ControlAddIn property on the field

  1. In Object Designer, click Page.

  2. Select the page with ID 21 and name Customer Card, and then click Design.

  3. Select the Name field, and then on the View menu, click Properties.

  4. In the ControlAddIn property value, click the lookup button, and then select the MyCompany.MyProduct.FieldPopupAddin from the Client Add-in window.

  5. Click OK.

  6. Close the Properties window.

To set the add-in trigger in the C/AL Code

  1. On the View menu, click C/AL Code.

  2. In the C/AL Editor, locate the following trigger:

    CopyCode image Copy Code
    Name - OnControlAddIn(Index : Integer;Data : Text[1024])

  3. Add the following code:

    CopyCode image Copy Code
    Message(Data);

  4. Close the C/AL Editor.

  5. On the File menu, click Save, select Compiled, and then click OK.

To test the add-in

  • To test the add-in, in Object Designer, select the Customer Card page, and then click Run.

Expand image See Also

Tasks

How to: Create a RoleTailored Client Control Add-in
How to: Determine the Public Key Token of the RoleTailored Client Control Add-in
How to: Install a RoleTailored Client Control Add-in Assembly
How to: Register a RoleTailored Client Control Add-in
How to: Set up a RoleTailored Client Control Add-in on a Page

Concepts

RoleTailored Client Control Add-in Overview
Developing RoleTailored Client Control Add-ins
Client Extensibility API Overview
Binding a RoleTailored Client Control Add-in to the Database
Calling C/AL Triggers from a RoleTailored Client Control Add-in
Installing and Configuring RoleTailored Client Control Add-ins on Pages


Improving Application Performance

Improving Application Performance

This topic covers features built into C/SIDE to increase performance, such as the DBMS cache, the commit cache, and the command buffer. It also contains a section on how keys and queries can affect performance.

To | See
Learn the purpose and function of DBMS cache. | DBMS Cache
Learn the purpose and function of the commit cache. | Commit Cache
Learn the purpose and function of the command buffer. | Command Buffer
Learn the purpose and function of keys, queries, and performance. | Keys, Queries, and Performance
Learn how you can use bulk inserts to improve SQL Server performance. | Bulk Inserts
Learn more about setting configuration parameters. | Configuration Parameters
Learn more about C/AL database functions and performance on SQL Server. | C/AL Database Functions and Performance on SQL Server
Learn more about creating login stored procedures on the SQL Server Option. | Login Stored Procedure on the SQL Server Option


DBMS Cache

DBMS Cache

The Database Management System (DBMS) is a memory buffer which stores copies of portions of the database that the DBMS is currently using. Reading from memory is much faster than reading from the disk. The DBMS therefore returns a record more quickly if it is already stored in cache. As long as the required data is stored in cache, the data is immediately available. When the required data is not stored in cache, it must be copied from the disk and then stored in cache.

DBMS Cache Transparency

The DBMS cache is transparent to the user. For example, when a user requests data, the data is automatically copied into the cache and stored there. If the data is modified, it is automatically copied back to the physical disk. These data transfers take place automatically. The user does not need to know about the cache.

For example, three users send requests to the DBMS. When user 2 sends a request to read data from the database, the request handler determines whether the desired data can be fetched directly from the cache or whether it must be fetched from a disk.

At the same time, another user can modify a record in a table in the database. The modified data will be written to the DBMS cache, and not to the disk. When this user completes the write transaction (that is, commits the changes), the data in the cache that was modified during the transaction is written to the disk. The cache is then said to be flushed.

The DBMS cache always contains the most recently used data. The cache is continually updated with the relevant data from the database.

The size of the cache greatly affects performance. When you set the size of the cache, you must remember two simple rules:

  • The more memory you assign to the cache, the more efficient it becomes. (Of course, there is no reason to assign more memory to the cache than the total size of your database.)

  • The size of the cache must not exceed the amount of physical memory available on your system. This is because the operating system may swap the cache memory in and out of the disk. This will considerably slow down overall performance.

Note You must remember to specify the commitcache=yes server parameter in the command line to enable the caching of write transactions.

See Also

Concepts

Commit Cache
Command Buffer
Keys, Queries, and Performance
Bulk Inserts
Configuration Parameters
C/AL Database Functions and Performance on SQL Server
Login Stored Procedure on the SQL Server Option


Commit Cache

Commit Cache

The commit cache is a special write buffer for the disks in the system. The commit cache has been designed to:

  • Quickly absorb committed transactions from the Database Management System. This frees the DBMS to perform other tasks.

  • Enable asynchronous disk writes.

  • Enable parallel disk read and write operations when multiple disks are used.

  • Guarantee that the disk file is always consistent.

The Commit Cache Process

The commit cache is placed between the DBMS and the database. It absorbs committed transactions from the DBMS. When the commit cache receives a committed transaction, it writes the data to the disk. Thus the DBMS can perform other tasks while the commit cache writes to the disk. The data is written asynchronously to the disk because the disk write does not occur at the same time as the DBMS commits the transaction.

The logical database can be stored in several disk files, which can be stored on separate disks. When more than one disk is used to store the database, each of these disks is controlled by separate commit cache processes, which are linked together to both enable and control (asynchronous) parallel read and write operations.

The commit cache ensures that the database file is consistent even if a power failure occurs during a write operation to the disk. However, if a power failure occurs, you lose all the committed transactions that are currently contained in the commit cache.

The following figure illustrates a database that is stored on three physical disks. Each disk is controlled by its own commit cache process. These processes are connected to enable parallel reading and writing.

Note You should not use advanced disk caches with delayed write back. The use of such cache systems may corrupt your database files.

See Also

Concepts

DBMS Cache
Command Buffer
Keys, Queries, and Performance
Bulk Inserts
Configuration Parameters
C/AL Database Functions and Performance on SQL Server
Login Stored Procedure on the SQL Server Option


Command Buffer

Command Buffer

The command buffer only applies to Classic Database Server. It is placed as a link between your application and the DBMS and is temporary storage that can hold requests or C/AL database commands that are sent from your application to the DBMS. The command buffer has been designed to reduce the number of network transfers when using C/SIDE in local area network (LAN) environments.

The Command Buffer and Network Transfers

When an application performs a write transaction, some requests such as inserting a record in a table by using record.INSERT do not need to be sent to the DBMS immediately. They can be temporarily stored in a command buffer. In general, the commands that do not have to be sent to the DBMS immediately are the commands that do return a value.

Note Note

The contents of the command buffer are sent to the DBMS when the buffer is full or when a command requires an immediate response from the DBMS.

The advantage of assembling DBMS commands into packages is that the number of network transfers and the load on the LAN is reduced. The time that is required to send one DBMS request is comparable to the time that is used to send an entire package.

The following C/AL code example illustrates how the command buffer affects the number of network transfers.

CopyCode image Copy Code
WHILE Record.FIND('-') DO
Record.DELETE();

Two commands are executed for each record in the table. However, each record causes only one request to be sent to the DBMS because the DELETE command is stored in the command buffer until the FIND command is executed.

Debugging

The command buffer is turned off when you activate the C/AL debugger.

For example, the following statements illustrate the difference between running code with and without the debugger.

CopyCode image Copy Code
Customer."No." := '12';
Customer.DELETE();
First := 7;
Second := 0;
Ratio := First / Second;

If there is no customer with the number 12, then a run-time error occurs regardless of whether the debugger is active. However, the error that occurs is not the same. There are two errors because the customer cannot be found:

  • The DELETE statement will fail.

  • The last statement is a division by zero.

When the debugger is inactive, the DELETE command is stored in the command buffer for execution at a later time. Therefore, a run-time error occurs when the last statement tries to divide by zero.

When the debugger is active, the DELETE command is executed immediately. This causes a run-time error when the record for customer number 12 cannot be found.

See Also

Concepts

DBMS Cache
Commit Cache
Keys, Queries, and Performance
Bulk Inserts
Configuration Parameters
C/AL Database Functions and Performance on SQL Server
Login Stored Procedure on the SQL Server Option


Keys, Queries, and Performance

Keys, Queries, and Performance

When you write a query that searches through a subset of the records in a table, you need to be careful when you define the keys both in the table and in the query so that Microsoft Dynamics NAV can quickly identify this subset. For example, the entries for a specific customer will usually be a small subset of a table containing entries for all the customers.

Defining Keys to Improve Performance

The time that it takes to complete a query depends on the size of the subset. If a subset cannot be located and read efficiently, performance will deteriorate.

To maximize performance, you must define the keys in the table so that they facilitate the queries that you will have to run. These keys must then be specified correctly in the queries.

For example, you would like to retrieve the entries for a specific customer. To do this, you apply a filter to the Customer No. field in the Cust. Ledger Entry table. In order to run the query efficiently on SQL Server, you need to define a key in the table that has Customer No. as the first field. You must also specify this key in the query.

The table could have these keys.

CopyCode image Copy Code
Entry No.
Customer No.,Posting Date

The query could look like the following.

CopyCode image Copy Code
SETCURRENTKEY("Customer No.");
SETRANGE("Customer No.",'1000');
IF FIND('-') THEN
REPEAT
UNTIL NEXT = 0;

You should define keys and queries in the same way when you are using Classic Database Server. However, Classic Database Server can run the same query almost as efficiently if Customer No. is not the first field in the key. For example, if you have defined a key that contains Country/Region Code as the first field and Customer No. as the second field and if there are only a few different country/region codes used in the entries, the query will take about the same time to run.

The table could have these keys.

CopyCode image Copy Code
Entry No.
Country/Region Code, Customer No.,Posting Date

The query could look like the following.

CopyCode image Copy Code
SETCURRENTKEY("Country/Region Code","Customer No.");
SETRANGE("Customer No.",'1000');
IF FIND('-') THEN
REPEAT
UNTIL NEXT = 0;

SQL Server will not be able to answer this query efficiently and will read through the entire table. This is because SQL Server makes stricter demands than Classic Database Server on the way that keys are defined in tables and on the way they are used in queries. You should define your keys and queries with SQL Server in mind, as this will ensure that your application can run just as efficiently on both server options.

See Also

Concepts

DBMS Cache
Commit Cache
Command Buffer
Bulk Inserts
Configuration Parameters
C/AL Database Functions and Performance on SQL Server
Login Stored Procedure on the SQL Server Option


Bulk Inserts

Bulk Inserts

Microsoft Dynamics NAV automatically buffers inserts in order to send them to SQL Server at one time.

By using bulk inserts the number of server calls is reduced, thereby improving performance.

Bulk inserts also improve scalability by delaying the actual insert until the last possible moment in the transaction. This reduces the amount of time that tables are locked; especially tables that contain SIFT indexes.

Application developers who want to write high performance code that utilizes this feature should understand the following bulk insert constraints.

Bulk Insert Constraints

If you want to write code that uses the bulk insert functionality, you must be aware of the following constraints.

Records are sent to SQL Server when the following occurs:

  • You call COMMIT to commit the transaction.

  • You call MODIFY or DELETE on the table.

  • You call any FIND or CALC methods on the table.

Records are not buffered if any of the following conditions are met:

  • The application is using the return value from an INSERT call; for example, "IF (GLEntry.INSERT) THEN".

  • The table that you are going to insert the records into contains any of the following:

    • BLOB fields

    • Variant fields

    • RecordID fields

    • Fields with the AutoIncrement property set to Yes

The following code example cannot use buffered inserts because it contains a FIND call on the GL/Entry table within the loop.

CopyCode image Copy Code
IF (JnlLine.FIND('-')) THEN BEGIN
GLEntry.LOCKTABLE;
REPEAT
IF (GLEntry.FINDLAST) THEN
GLEntry.NEXT := GLEntry."Entry No." + 1
ELSE
GLEntry.NEXT := 1;
// The FIND call will flush the buffered records.
GLEntry."Entry No." := GLEntry.NEXT ;
GLEntry.INSERT;
UNTIL (JnlLine.FIND('>') = 0)
END;
COMMIT;

If you rewrite the code, as shown in the following example, you can use buffered inserts.

CopyCode image Copy Code
IF (JnlLine.FIND('-')) THEN BEGIN
GLEntry.LOCKTABLE;
IF (GLEntry.FINDLAST) THEN
GLEntry.Next := GLEntry."Entry No." + 1
ELSE
GLEntry.Next := 1;
REPEAT
GLEntry."Entry No.":= GLEntry.Next;
GLEntry.Next := GLEntry."Entry No." + 1;
GLEntry.INSERT;
UNTIL (JnlLine.FIND('>') = 0)
END;
COMMIT;
// The inserts are performed here.

See Also

Concepts

DBMS Cache
Commit Cache
Command Buffer
Keys, Queries, and Performance
Configuration Parameters
C/AL Database Functions and Performance on SQL Server
Login Stored Procedure on the SQL Server Option


Configuration Parameters

Configuration Parameters

You can configure a Microsoft Dynamics NAV database by creating a Microsoft SQL Server configuration parameter table. You need to enter parameters into the table to determine the behavior that will be used when using this database.

Creating a Configuration Parameter Table

To create a configuration parameter table, in the database create a table owned by dbo, as shown in the following code.

CopyCode image Copy Code
CREATE TABLE [$ndo$dbconfig] (config VARCHAR(512) NOT NULL)
GRANT SELECT ON [$ndo$dbconfig] TO public

You can add additional columns to this table, if necessary. The length of the config column should be large enough to contain the necessary configuration values, (512 is used in this example).

There is one record in this table for each required parameter.

See Also

Concepts

DBMS Cache
Commit Cache
Command Buffer
Keys, Queries, and Performance
Bulk Inserts
C/AL Database Functions and Performance on SQL Server
Login Stored Procedure on the SQL Server Option


Index Hinting

Index Hinting

On Microsoft SQL Server, you can use index hinting to force the server to use a particular index when executing queries for FINDFIRST, FINDLAST, FINDSET, FIND('-'), FIND('+'), FIND('='), and GET statements.

Index hinting can prevent situations where SQL Server's Query Optimizer chooses an index access method that requires many page reads and generates long-running queries with response times that vary from seconds to several minutes. Directing SQL Server to use a specific index can give instant 'correct' query executions with response times of milliseconds. Index hints should only be used to target specific problems.

There are two ways to use index hinting in your application:

  • You can leave index hinting turned off and enable it in specific places.

  • You can turn on index hinting and disable it in specific places.

In Microsoft Dynamics NAV, index hinting is turned off by default.

The Benefits of Using Index Hinting

Index hinting has been shown to optimize performance in the following scenarios:

  • Index hints prevent SQL Server from using an old query plan, such as a clustered index scan.

  • Index hints prevent SQL Server from scanning smaller tables and escalating locks to table locks.

Prerequisite

To benefit from index hinting, you must use SETCURRENTKEY in your application code. SETCURRENTKEY must correspond to the filter that you want to place on the table.

CopyCode image Copy Code
GLEntry.SETCURRENTKEY(GLEntry.AccountNo);
// Should be added to the code if it is not already present.
GLEntry.SETRANGE(GLEntry.AccountNo,'1000','9999');
GLEntry.FINDSET();

Example:

In the following C/AL code, index hinting is turned on but SETCURRENTKEY is not used.

CopyCode image Copy Code
GLEntry.SETRANGE("G/L Account No.",'2910');
GLEntry.FINDSET;

This generates the following SQL query.

CopyCode image Copy Code
SELECT TOP 500 * FROM "W1403"."dbo"."CRONUS International Ltd_$G_L
Entry" WITH (READUNCOMMITTED, INDEX("CRONUS International Ltd_$G_L
Entry$0")) WHERE (("G_L Account No_"=@P1)) ORDER BY "Entry No_"
','2910'

Without using SETCURRENTKEY, Microsoft Dynamics NAV will hint the SQL index that corresponds to the primary key in the G/L Account table. This is not the best key to use for this query. Conversely, in the following C/AL code, hinting is turned on and SETCURRENTKEY is used.

CopyCode image Copy Code
GLEntry.SETCURRENTKEY("G/L Account No.");
GLEntry.SETRANGE("G/L Account No.",'2910');
GLEntry.FINDSET;

This generates the following SQL query.

CopyCode image Copy Code
SELECT TOP 500 * FROM "W1403"."dbo"."CRONUS International Ltd_$G_L
Entry" WITH (READUNCOMMITTED, INDEX("$1")) WHERE (("G_L Account
No_"=@P1)) ORDER BY "G_L Account No_","Posting Date","Entry No_"
','2910'

Because the C/AL code specifies which key to use, Microsoft Dynamics NAV hints the corresponding index from the code, ensuring that the correct index is always used.

If index hinting is turned off, SQL Server will define the filter automatically.

Disabling Index Hinting in Specific Places

If you decide to turn on index hinting, you can still disable it for a specific company, table, or index. The following examples illustrate how to disable index hinting by executing a statement in query analyzer.

Example 1

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=No')

Index hinting is turned off across the entire application.

Example 2

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=No;Company="CRONUS International Ltd."')

Index hinting is turned off only for the CRONUS International Ltd. company.

Example 3

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=No;Company="CRONUS International Ltd.";Table="Sales
Header')

Index hinting is turned off only for the CRONUS International Ltd_$Sales Header table.

Example 4

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=No;Company="CRONUS International Ltd.";Table="Sales
Header";Index="1"')

Index hinting is turned off only for the $1 index in the CRONUS International Ltd_$Sales Header table.

Enabling Index Hinting in Specific Places

You can disable index hinting for the entire system and then enable it where appropriate for your application. The index hint syntax is:

CopyCode image Copy Code
IndexHint=<Yes,No>;Company=<company name>;Table=<table name>;Key=<keyfield1,keyfield2,...>; Search Method=<search method list>;Index=<index id>

Each parameter keyword can be localized in the Driver configuration parameters section of the .stx file.

The guidelines for interpreting the index hint are:

  • If a given keyword value cannot be matched, the entry is ignored.

  • The values for the company, table, key fields, and search method must be surrounded by double-quotes to delimit names that contain spaces, commas, and so on.

  • The table name must correspond to the name supplied in Object Designer (not the caption name).

  • Key must contain all the key fields that match the required key in the Keys window in Table Designer.

  • The Search method contains a list of search methods used in FIND statements.

    Function Symbol

    RECORD.GET()

    !

    RECORD.FIND()

    =

    RECORD.FIND('-')

    -

    RECORD.FIND('+')

    +

    RECORD.FIND('>')/RECORD.NEXT()

    >

    RECORD.FIND('<')/RECORD.PREV()

    <

    RECORD.FINDFIRST()

    [

    RECORD.FINDLAST()

    ]

    RECORD.FINDSET()

    $

  • The index ID corresponds to a SQL Server index for the table: 0 represents the primary key; all other IDs follow the number included in the index name for all the secondary keys. Use the SQL Server command sp_helpindex to get information about the index ID associated with indexes on a given table. The following example looks for index information about the Item Ledger Entry table.

    CopyCode image Copy Code
    sp_helpindex 'CRONUS International Ltd_$Item Ledger Entry'

When a query is executed, it checks whether the query is for the company, table, current key, and search method listed in one of the IndexHint entries. If it is, it will hint the index for the supplied index ID in that entry. The following rules apply:

  • If the company is not supplied, the entry matches all the companies.

  • If the search method is not supplied, the entry matches all the search methods.

  • If the index ID is not supplied, the index hinted is the one that corresponds to the supplied key. This is probably the desired behavior in most cases.

  • If the company, table, or fields are renamed or the table's keys are redesigned, the IndexHint entries must be modified manually.

The following examples illustrate how to add an index hint to the table by executing a statement in Query Analyzer.

Example 1

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=Yes;Company="CRONUS International Ltd.";Table="Item
Ledger Entry";Key="Item No.","Variant Code";Search Method="-
+";Index=3')

This will hint the use of the $3 index of the CRONUS International Ltd_$Item Ledger Entry table for FIND('-') and FIND('+') statements when the Item No.,Variant Code key is set as the current key for the Item Ledger Entry table in the CRONUS International Ltd. company.

Example 2

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=No;Company="CRONUS International Ltd.";Table="Item
Ledger Entry";Key="Item No.","Variant Code";Search Method="-
+";Index=3')

The index hint entry is disabled.

Example 3

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=Yes;Company="CRONUS International Ltd.";Table="Item
Ledger Entry";Key="Item No.","Variant Code";Search Method="-
+";Index=')

This will hint the use of the Item No.Variant Code index of the CRONUS International Ltd_$Item Ledger Entry table for FIND('-') and FIND('+') statements when the Item No.,Variant Code key is set as the current key for the Item Ledger Entry table in the CRONUS International Ltd. company.

This is the most commonly used index-hinting feature.

Example 4

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=Yes;Company=;Table="Item Ledger Entry";Key="Item
No.","Variant Code";Search Method="-+";Index=3')

This will hint the use of the $3 index of the CRONUS International Ltd_$Item Ledger Entry table for FIND('-') and FIND('+') statements when the Item No.,Variant Code key is set as the current key for the Item Ledger Entry table for all the companies (including a non-company table with this name) in the database.

Example 5

CopyCode image Copy Code
INSERT INTO [$ndo$dbconfig] VALUES
('IndexHint=Yes;Company="CRONUS International Ltd.";Table="Item
Ledger Entry";Key="Item No.","Variant Code";Search Method=;Index=3')

This will hint the use of the $3 index of the CRONUS International Ltd_$Item Ledger Entry table for every search method when the Item No.,Variant Code key is set as the current key for the Item Ledger Entry table in the CRONUS International Ltd. company.

See Also

Concepts

Improving Application Performance
SETCURRENTKEY, SETRANGE, SETFILTER, GETRANGEMIN, and GETRANGEMAX Functions


C/AL Database Functions and Performance on SQL Server

C/AL Database Functions and Performance on SQL Server

This topic describes the relationship between basic database functions in C/AL and SQL statements.

C/AL and SQL Statements

GET, FIND, and NEXT

Each GET (or FIND('=')) operation requires a separate SQL statement unless the client has already retrieved the desired record during a recent operation. If the client reads the same record several times, then SQL Server is only called the first time that the client needs to read the record.

Each FIND('-/+') operation requires a separate SQL statement unless the client has executed the same query (filters) in a recent operation.

Each NEXT (or FIND('>/<')) operation requires at least one SQL statement.

However, when NEXT is used with FIND('-/+') to read a set, as shown in the following example, one SQL statement can cover the needs of all NEXT function calls in the loop.

CopyCode image Copy Code
IF FIND('-') THEN
  REPEAT
    // Insert statements to repeat.
  UNTIL NEXT = 0;

Reading the set backwards with FIND('+')/NEXT(-1) or using the ASCENDING Function (Record) is equally efficient. You should not read record sets by using "WHILE FIND('- /+') DO" or any similar constructions.

FINDSET

The FINDSET operation optimizes reading records from SQL Server by establishing a stream of records between Microsoft Dynamics NAV and SQL Server. While the stream is open, no other activity occurs between Microsoft Dynamics NAV and SQL Server. Before the records are read, Microsoft Dynamics NAV has no information about how many records are available to read. However, Microsoft Dynamics NAV must allocate enough memory to accommodate all records that it will read for the FINDSET operation. The stream does not allow it to read records in groups. Microsoft Dynamics NAV allocates memory for a preset number of records and then begins reading the records. You can change the value of this preset number by changing the Record Set value in the New Database or Alter Database window. For more information, see the topic "Entering Information in the New Database - Advanced Tab" in the Microsoft Dynamics NAV Application Help.

Note Note

In Microsoft Dynamics NAV 2009, the default value is 50. In Microsoft Dynamics NAV 5.0, when the FINDSET operation was introduced, the default value was 500.

If the number of records that is read falls within this range, then all records are read with optimized performance. If there are more records to read than the preset number, then Microsoft Dynamics NAV must establish new commands to SQL Server to continue reading records. Microsoft Dynamics NAV reads all records successfully, but the additional commands are expensive for SQL Server to execute. The FIND('-') operation is more efficient than the FINDSET operation when there are more records to read than the preset number.

You must decide when to use the FINDSET operation and when to use the FIND('-') operation based on the maximum number of records to read and the value of the Record Set preset number.

Note Note

If Microsoft Dynamics NAV detects a pattern in which FINDSET would be a better choice than FIND, then it converts the FIND operation to a FINDSET operation.

CALCFIELD and CALCSUMS

Each CALCFIELD or CALCSUMS operation that calculates a sum requires a separate SQL statement unless the client has calculated the same sum or another sum that uses the same SumIndex or filters in a recent operation.

Each CALCFIELD or CALCSUMS request should be confined to use only one SIFT index. The SIFT index can only be used if:

  • All requested sum-fields are contained in the same SIFT index.

  • The specified filter matches a SIFT index containing all the sum-fields.

If neither of these requirements is fulfilled, then the sum will be calculated directly from the base table.

INSERT, MODIFY, DELETE, and LOCKTABLE

Each INSERT, MODIFY, or DELETE operation requires a separate SQL statement. If the table that you modify contains SumIndexes, then the operations will be considerably slower. As a test, select a table that contains SumIndexes and execute one hundred of these INSERT, MODIFY, or DELETE operations to measure how long it takes to maintain the table and all its SumIndexes.

The LOCKTABLE operation does not require any separate SQL statements. It only causes any subsequent reading from the table to lock the table or parts of it.

See Also

Concepts

DBMS Cache
Commit Cache
Command Buffer
Keys, Queries, and Performance
Bulk Inserts
Configuration Parameters
Login Stored Procedure on the SQL Server Option


Login Stored Procedure on the SQL Server Option

Login Stored Procedure on the SQL Server Option

A login stored procedure is a stored procedure that you can use to perform predefined functions after a user logs on to Microsoft Dynamics NAV with Microsoft SQL Server. A typical function would be to generate a message informing the user that the database is currently in single-user mode so that an administrator can perform database maintenance tasks and is therefore inaccessible.

The login stored procedure is run immediately after the user has logged on to SQL Server and opened a database and before Microsoft Dynamics NAV carries out any tasks including executing any C/AL triggers. The user must have successfully logged on to the server and have access to the database before the stored procedure is run.

Creating the Stored Procedure

The stored procedure is created in the database and has a predefined name and a list of parameters.

The stored procedure is called [sp_$ndo$loginproc] and has the following characteristics:

  • It takes two VARCHAR parameters: the name of the application and the C/SIDE version number. These parameters must be declared as part of the stored procedure but do not have to be used.

  • It can perform transactions. Microsoft Dynamics NAV uses a COMMIT to flush any outstanding transactions after the stored procedure has finished executing.

  • The RAISERROR statement can be used to display an error message in Microsoft Dynamics NAV and prevent the user from accessing the database.

  • The PRINT statement can be used to display a warning in Microsoft Dynamics NAV and allow the user to access the database.

  • If the stored procedure returns a value, it is ignored.

  • If the stored procedure does not exist, no action is taken by Microsoft Dynamics NAV and the login process continues as usual.

The following examples show how to create a login procedure in the Query Analyzer tool. The database must be selected before these statements are executed.

Example 1

The following code example displays a warning message in Microsoft Dynamics NAV and permits the login.

CopyCode image Copy Code
IF EXISTS (SELECT name FROM sysobjects
WHERE name = 'sp_$ndo$loginproc' AND type = 'P')
DROP PROCEDURE [sp_$ndo$loginproc]
GO
CREATE PROCEDURE [sp_$ndo$loginproc]
@appname VARCHAR(64) = NULL,
@appversion VARCHAR(16) = NULL
AS
BEGIN
PRINT 'The system will be unavailable on Sunday April 1.'
END
GO
GRANT EXECUTE ON [sp_$ndo$loginproc] TO public
GO

Example 2

The following code example displays an error message in Microsoft Dynamics NAV and prevents the login.

CopyCode image Copy Code
IF EXISTS (SELECT name FROM sysobjects
WHERE name = 'sp_$ndo$loginproc' AND type = 'P')
DROP PROCEDURE [sp_$ndo$loginproc]
GO
CREATE PROCEDURE [sp_$ndo$loginproc]
@appname VARCHAR(64) = NULL,
@appversion VARCHAR(16) = NULL
AS
BEGIN
IF SUSER_SNAME() IN ('ACCOUNTS\jim', 'SALES\bill')
RAISERROR ('Contact the system administrator.', 11, 1)
END
GO
GRANT EXECUTE ON [sp_$ndo$loginproc] TO public
GO

See Also

Concepts

DBMS Cache
Commit Cache
Command Buffer
Keys, Queries, and Performance
Bulk Inserts
Configuration Parameters
C/AL Database Functions and Performance on SQL Server


Creating a More Secure Application

Creating a More Secure Application

This section introduces you to the Microsoft Dynamics NAV security system. It explains the different layers of security that exist in Microsoft Dynamics NAV and how they work.

Implementing Security

To | See
Learn about the different layers of security in Microsoft Dynamics NAV. | Security
Learn about business areas, functional areas, and granules in the general ledger. | Business Areas and Granules
Read about record level security and using security filters. | Supporting Record-Level Security

See Also

Concepts

Improving Application Performance


Security

Security

The Microsoft Dynamics NAV security system allows you to control which objects or tables a user can access within each database. You can specify the type of access that each user has to these objects and tables, whether they are able to read, modify, or enter data.

The Microsoft Dynamics NAV Security System

Using Microsoft Dynamics NAV with Microsoft SQL Server, you can specify which records are stored in the tables that each user is allowed to access. This means that permissions can be allocated at both the table level and the record level.

The security system contains information about the permissions that have been granted to each user who can access a particular database.

This information includes the roles that the users have been assigned, as well as any permissions that they have been granted to individual users.

There are four different levels of security:

  • Database

  • Company

  • Object

  • Record

Graphically, these can be represented as the layers, where the central layer is the records in the database.

See Also

Concepts

Database-Level Security
Windows Logins
Database Logins
Company-Level Security
Object-Level Security
Permissions on Database Objects
Record-Level Security
Security Considerations


Database-Level Security

The first layer of security when you open Microsoft Dynamics NAV is database security.

Database-Level Security

After you start Microsoft Dynamics NAV and attempt to open the database, your credentials are checked. If you have not been granted permission to open the database you receive an error message.

To open a database, click File, click Database, and then click Open. The Open Database window appears. In this window you can use the AssistButton to locate the server that you want to access and the database that you want to open. If you are running on Classic Database Server, you can select the server from a list of Classic Database Servers. If you are running on SQL Server, you can select the server from a list of SQL Servers.

In the Authentication field, select the type of authentication that you want to use to verify your credentials and give you access to the database. The following kinds of authentication are supported:

  • Windows Authentication

  • Database Authentication

The authentication that you use depends on which kind of login that you have been granted.

See Also

Concepts

Security
Business Areas and Granules


Company-Level Security

Company-Level Security

After you have gained access to the database, you can open the company that you want to work with.

Opening a Company

To open a company, click File, click Company, and then click Open. The Open Company window appears. This window lists all of the companies that have been created in the current database and that you have been given access to. A Microsoft Dynamics NAV database can contain several companies. Each company can use its own tables and can also share tables with other companies.

Select the company that you want to open, click OK, and the company opens. If there are companies in the database that you have not been given permissions to access, you will not be able to see them in this window.

See Also

Concepts

Security
Business Areas and Granules
Object-Level Security


Object-Level Security

When you open a company in Microsoft Dynamics NAV, your ability to access information is determined by the security system.

Object-Level Security

The Microsoft Dynamics NAV security system consists of roles and permissions that you can assign to users who have access to the company. The security roles determine the access that users have and the tasks that users can perform on the objects that exist in the database.

Security System Database Objects

The security system divides the database into the following objects.

Object | Description
Table Data | The actual data that is stored in the tables.
Table | The tables themselves.
Form | The forms that are used to view and enter data.
Report | The reports that are used to present the data.
Dataport | The dataports that are used to import and export data.
Codeunit | The codeunits that are used in the database.
XMLport | The XMLports that are used to import and export data in XML format.
MenuSuite | The object that contains the menus that are displayed in the navigation pane.
System | The system tables in the database that allow the user to make backups, change license files, and so on.

The various roles that exist in Microsoft Dynamics NAV determine the tasks that you can perform on these objects. For more information about permissions, see Permissions on Database Objects.

Example of Permissions on Database Objects

The following example is taken from a table Microsoft Dynamics NAV called FA-JOURNAL, POST Post FA journals - Permissions. It illustrates how permissions on database objects are allocated. This example shows the permissions that have been granted to the FA – Journal, Post role. As you can see, this role has been granted permission to perform different tasks on various objects.

Object type | Object ID | Object name | Read permission | Insert permission | Modify permission | Delete permission | Execute permission
Table Data | 5619 | FA Journal Template | Yes | Yes |  |  |
Table Data | 5620 | FA Journal Batch | Yes | Yes |  | Yes |
Table Data | 5621 | FA Journal Line | Yes | Yes | Yes | Yes |
Table Data | 5622 | FA Reclass. Journal Template | Yes | Yes |  |  |
Table Data | 5623 | FA Reclass. Journal Batch | Yes | Yes |  | Yes |
Table Data | 5624 | FA Reclass. Journal Line | Yes | Yes | Yes |  |
Table Data | 5625 | Maintenance Ledger Entry | Indirect | Indirect | Indirect |  |
Table Data | 5626 | Maintenance | Yes |  |  |  |
Table Data | 5629 | Ins. Coverage Ledger Entry | Indirect |  | Indirect |  |

See Also

Concepts

Security
Business Areas and Granules
Permissions on Database Objects


Record-Level Security

Record-level security allows you to limit the access that a user has to the data in a table. You do this by specifying that the user only has permission to access certain records in the table. Record level security is only available in Microsoft Dynamics NAV with Microsoft SQL Server.

Record-Level Security

Record-level security is implemented by applying security filters to the tables and the table data that a user has access to. You can specify, for example, that a user can only read the records that contain information about a particular customer. This means that the user cannot access the records that contain information about other customers.

See Also

Concepts

Security
Business Areas and Granules
Security Considerations


Windows Logins

Windows Logins

When you use Windows authentication to control access to Microsoft Dynamics NAV, users are given a Windows login. Windows logins correspond to the Windows users and groups of the Windows domain. These are administered and listed in a separate table and window.

How Windows Logins Work

With Windows authentication, when a user tries to connect to a server and open a database, he does not have to supply a user ID or password. Microsoft Dynamics NAV automatically determines whether a user, who has already logged on to the network, has a valid Windows account and access is granted to a particular server.

If the user is allowed to access the server, Microsoft Dynamics NAV checks to see if the user has been assigned a Windows login within Microsoft Dynamics NAV. If the user has a Windows login, he will be granted access to the database.

The user will be granted access to Microsoft Dynamics NAV and be given the permissions specified for that Windows user and those specified for any Windows groups of which he is a member.

If the user does not have a valid Windows account or if the account does not include permission to log on to the Microsoft Dynamics NAV database, authentication fails, and the user receives an error.

See Also

Concepts

Security
Database Logins
Business Areas and Granules


Database Logins

Database Logins

Users are given a database login when they have their own user ID and password in Microsoft Dynamics NAV. The user must enter the user ID and password to access the database.

How Database Logins Work

Using the SQL Server Option, users must also have a login on SQL Server. SQL Server has its own authentication of the user’s ID and password. SQL Server does this by checking whether a SQL Server login with this user’s ID and password has been created.

This login must first be created by a SQL Server administrator, with a SQL Server tool. If a SQL Server login has not been set up, authentication fails and the user receives an error.

The user is granted access to the server after his login has been authenticated. Database security then validates the user’s permissions by checking the database user accounts on the server. The permissions that the user has been granted to the various objects within the database, such as tables, are determined by the information contained in the user’s database user account. This account also contains information about any additional permissions that the user may have been granted to alter the database itself.

See Also

Concepts

Security
Windows Logins
Company-Level Security


Permissions on Database Objects

Permissions on Database Objects

This section gives an overview of the permissions that a role can have on an object.

Permissions

If you have been granted permission to read a form, you can open the form and view the data that it displays. If, however, you do not have write permission, you are not allowed to enter data into this form.

Sometimes, when you open a form it displays information from several tables. To access this form, you must have permission to view all the data displayed by the form. You might not have permission to read directly from all the tables that the form uses. In this case, you must have indirect permission to read from the tables in question. Having indirect permission to a table means that you cannot open the table and read from it but can only view the data it contains indirectly through another object, such as a form or report, that you have direct permission to access.

Microsoft Dynamics NAV has a number of standard predefined security roles. You can use these roles as defined or you can change the roles to suit your particular needs. You can also create your own security roles and give them the permissions that you want.

Permissions That a Role Can Have On an Object

Permission | Description
Read | You can read this object.
Insert | You can insert data into this object.
Modify | You can modify data in this object.
Delete | You can delete data from this object.
Execute | You can run this object.

See Also

Concepts

Security
Business Areas and Granules
Record-Level Security


Security Considerations

Security Considerations

The following list contains some important things to consider when setting up your Microsoft Dynamics NAV security system.

  • The Microsoft Dynamics NAV security system is initiated when you create the first login. Until you create the first login, any user can have full access to carry out any transaction in a Microsoft Dynamics NAV database. Therefore, the first login that you create must be a superuser. The superuser must own and administer all access to the database from within Microsoft Dynamics NAV. We recommend that the user who administers security in Microsoft Dynamics NAV be a superuser.

  • One of the first things that the superuser should do is create logins for the other users that will have access to the database and grant them the appropriate permissions.

  • In Microsoft Dynamics NAV, a table can contain a FlowField, which generates sums based on values that are stored in another table. When using a FlowField, a user must have permission to read both tables or they will not be allowed to read the first table.

See Also

Concepts

Security
Database Logins
Windows Logins


Business Areas and Granules

Microsoft Dynamics NAV contains business areas. You can control how the license file controls the access that you have to these business areas and the functionality that they contain.

Business Areas and Granules

The standard Microsoft Dynamics NAV application is divided into several business areas. Each business area consists of a number of functional areas. These functional areas contain functionality; however different customers might only need some of the functionality that is provided. To facilitate this, a Microsoft Dynamics NAV license file contains a number of granules. Each granule represents a small area of functionality.

This system makes it possible for each customer to purchase a license that only gives the company and the company's employees access to exactly the functionality needed.

See Also

Concepts

Business Areas and Functional Areas
Granules Available in the General Ledger


Business Areas and Functional Areas

Microsoft Dynamics NAV is divided into several business areas. Each business area consists of a number of functional areas.

Business Areas and Functional Areas

The following table shows all of the business areas and functional areas. Each functional area represents an important field of activity.

Business areas | Functional areas
Finance Management | Cash Management Fixed Assets General Ledger Inventory Payables Receivables
Sales & Marketing Sales | Analysis & Reporting History Inventory & Pricing Marketing Order Processing
Purchase | Analysis & Reporting History Inventory & Costing Order Processing Planning
Warehouse | Goods Handling History Inventory Orders & Contacts Planning & Education
Manufacturing | Capacities Costing Execution History Planning Product Design
Jobs | History Jobs Periodic Activities Reports
Resource Planning | History Periodic Activities Reports Resources
Service | Contact Management History Order Processing Planning & Dispatching
Human Resources | Absence Registration Employees Reports
IT Administrator | Application Setup IT Administration

See Also

Concepts

Granules Available in the General Ledger


Granules Available in the General Ledger

This topic contains a list of granules that are available in the General Ledger. The information in the table below does not necessarily correspond with the granule definition that is currently enforced by Microsoft Dynamics NAV.

Each of the other functional areas can be similarly broken down into areas of more specific functionality. This means that your license file and the way that it is configured have an important influence on the functionality that is available to you in Microsoft Dynamics NAV. Your license file and the granules that it contains determine which functional areas you have access to and which functions you can perform in these areas. The advantage of this system is that the customer does not pay for a general license to run the product but only pays for the granules that they need to run their business.

Granules Available in the General Ledger

The following table lists the granules that are available in the General Ledger.

Granule name and number Description

Basic General Ledger (3,010)

You use this granule to set up a company and post to the general ledger.

This granule provides you with the basic features necessary for setting up a company and posting to the general ledger, chart of accounts, general journals, VAT facilities, recurring journals, and source codes. It also includes features for internal and external reporting.

This granule allows you to post and report in the company's base currency. If you also purchase the Multiple Currencies granule, you can post and report in an additional currency.

This granule allows you to use two languages—the U.S. English language and the native language for the particular country/region.

This granule allows one instance of Classic Application Server.

This granule must always be included as part of the initial purchase of Microsoft Dynamics NAV because it includes one session and the first company.

Requirements: Microsoft Dynamics NAV Version 3.XX

Budgets (3,030)

This granule allows you to work with budgets in general ledger accounts.

After you have created a budget, you can print a balance compared to the budget, which shows variances by percentages. Budgets are normally entered per period for the relevant general ledger accounts. You can create, copy, and work with any number of budgets at the same time. You can work with, for example, a 100% budget, a 110% budget, and so on.

Requirements: Basic General Ledger

Account Schedules (3,040)

You use this granule for financial reporting. You can arrange reports based on the figures in the chart of accounts and budgets, but with a different arrangement for financial figures, text, or details than in the chart of accounts. The Account Schedules granule is like a filter for the chart of accounts that enables you to choose the accounts that you want to include. You can also use it to change the order of the accounts or combine the figures in various ways, and set up which columns to print. In addition, it is possible to make simple calculations.

Requirements: Basic General Ledger

Consolidation (3,050)

This granule enables you to consolidate companies in Microsoft Dynamics NAV.

The companies can come from one or from several different Microsoft Dynamics NAV databases or from another type of file. You can import and export financial information in this granule. If the data is retrieved from several Microsoft Dynamics NAV solutions, the granule is only used in the parent company itself.

Requirements: Basic General Ledger

Allocations (3,020)

This granule allows you to allocate general ledger entries so you can have combinations of accounts, departments, and projects using allocation keys.

The allocation keys can be based on amount, percentage, or quantity.

Allocations can be used for many purposes, for example, to allocate overhead, such as rent, to company profit centers.

Requirements: Basic General Ledger

Responsibility Centers (3,060)

With this granule you can setup profit centers and cost centers. A company can sell items with specific prices and related to a responsibility center. This granule enables you to associate a user to a responsibility center so that only sales and purchase documents related to the particular user are displayed. In addition, users get assistance when entering extra data, such as dimensions and location codes.

Requirements: Multiple Locations

Basic XBRL (3,070)

With this granule you can export documents from Microsoft Dynamics NAV in XBRL format and import XBRL taxonomies into Microsoft Dynamics NAV from the Internet, e-mail, or from other systems. XBRL is an XML-based specification that uses accepted financial reporting standards based on standardized, underlying data tags. It is possible to map your general ledger to XBRL taxonomies, meaning that the same XBRL instance document can be used for various purposes, independent of the format required by the receiver of the document.

Requirements: Basic General Ledger

Change Log (3,080)

This granule enables you to log user changes made to Microsoft Dynamics NAV master data.

It is possible to log all direct modifications that a user makes to the data in the database, except changes to 'working documents' such as journals, sales orders, and purchase orders. The change log functionality makes it possible to get a chronological list of all changes to any field in any table and to see who (what user ID) made the changes.

Requirements: Basic General Ledger

See Also

Concepts

Business Areas and Functional Areas


Supporting Record-Level Security

Supporting Record-Level Security

This section explains how to implement record-level security in Microsoft Dynamics NAV with Microsoft SQL Server.

Microsoft Dynamics NAV with Microsoft SQL Server allows you to limit the access that users have to the information stored in the database by specifying that they can only access records which fulfill certain criteria in specific tables. This is called record-level security. You implement record-level security by placing security filters on the roles and permissions that you assign to your users.

Security Filters

It is important to remember that when using security filters, the filters must reflect the business logic of your application if you are to avoid problems.

Record-level security has no influence on the business logic of your application but the business logic of your application can have a great influence on record-level security and the filters that you can apply. Record-level security is only useful when it complements or supplements your business logic.


Implementing Record-Level Security

Implementing Record-Level Security

After you have set up your record-level security filters, Microsoft Dynamics NAV automatically applies them in most situations. This means that the user only receives an error message if the user manually attempts to access data that is outside the range of the security filters that have been defined.

How C/SIDE Applies Record-level Security

When a form is opened from a command button or menu item, C/SIDE automatically applies record-level security filters to the main record variable used in the form, provided that the command button or menu item in question uses properties to run the form, and not code.

Similarly, when a report or dataport is opened from a command button or menu item, C/SIDE automatically applies record-level security filters to all the record variables used in the request filter tabs, provided that the command button or menu item in question uses properties to run the report or dataport, and not code.

C/SIDE does not apply record-level security filters to user-defined global and local variables. To help users stay within the defined security filters, you must include the appropriate statements in the code that applies the filters. Security filters are applied on a record variable by using the SETPERMISSIONFILTER function that is available for the record variable.

Example

The following code example finds the first record within your read-permission security filter.

CopyCode image Copy Code
Customer.SETPERMISSIONFILTER;
Customer.FIND('-');

Record-level security filters affect performance in the same way as other filters that are applied by the user. It is important that the record-level security filters have matching keys in tables that contain many records, and that these keys are used. C/SIDE does not automatically select the most effective key to use. If, for example, a security filter specifies that a user is only allowed to see records that he created by placing a filter on a field called User ID, the matching key must start with User ID. Furthermore, to ensure the best performance, the user must select the User ID key when opening the form for the first time. In some situations you can choose to change the default sorting in the form, or in the command buttons, menu items, and code that opens the form.

See Also

Concepts

Forms, Reports, and Dataports
Codeunits


Forms, Reports, and Dataports

Forms, Reports, and Dataports

When a form, report, or dataport is opened from a command button or menu item, C/SIDE automatically applies record-level security filters if the command button or menu item uses properties instead of code to run the form. If the form is simple, then the security filters that you apply at the user level ensure that the degree of security that you want is implemented.

Find('+') and Calcsums

If the report or form contains complex C/AL code, such as Find('+'), or contains a calcsum, then the security filters that are applied at user level do not ensure that the form or report can run successfully. In this case, the user may receive an error message about not having read permission to a particular table.

This situation generally arises because the form or report contains functionality that requires access to all records in the table. This conflicts with the user’s security filters, which only allow access to some records in the table. For example, if the form needs to read the last record in the table before it can insert a new record and the last record in the table lies outside the range of the security filter that has been applied to the user, then the user sees the error.

The user has already been assigned a role that allows access the records in the table. This role was then limited to only some records in the table by a security filter. To resolve this conflict, you must augment the user's permissions by assigning a new role that allows indirect read access to all records in the table.

Granting the user indirect permission to read the entire table does not compromise the integrity of the security system. The user still cannot see the records that are outside the range of the security filter. But the application can perform the calculations and read all data that is necessary to function correctly and give the user the required information.

This solution works because security permissions are added together and are not mutually exclusive.

See Also

Concepts

Implementing Record-Level Security
Codeunits


Codeunits

A typical Microsoft Dynamics NAV application contains forms and reports which include complex functionality that requires the form or report to run individual codeunits or chains of codeunits. These codeunits can contain code that accesses different tables.

Codeunits

Codeunits are independent objects that have their own permissions.

They are not assigned roles but rather given permission to access various tables. The permissions for a codeunit are part of its properties. These permissions are indirect because codeunits can only access an object after they have been activated by a user who has permission to run the form or report that calls the codeunit.

When a user runs a form that calls a codeunit the security filters that have been applied to the user’s permissions might be compatible with the permissions that have been defined for the codeunit. If they are incompatible, the user will receive an error message informing them that they do not have permission to access a particular table.

To resolve this conflict, you must ensure that the user’s security filters are compatible with the permissions defined for the codeunit. To do this, you need to assign the user a new role that gives them indirect read access to all the records in the table and then open the codeunit in the Object Designer, open the Properties window, and then give the codeunit read permission to the table in question.

If the error message is not informative, you need to use the Debugger to identify the point at which the code errors. This will help you identify the table involved and you can then give the codeunit read permission to it.

You should then run the form again. If you receive another error message, you can repeat this procedure until the form runs successfully.

It is also possible that your license does not allow you to modify the codeunits in question. In this case, you must contact your local Microsoft Dynamics NAV Partner.

Guidelines for Implementing Record Level Security

The following guidelines are some general rules for implementing record level security:

  • Record level security and the business logic of the application must work together.

  • For forms, reports, and dataports that are run by properties and not code, the security filters that you apply at user level are sufficient.

  • For forms, reports, and dataports that run code, assign an extra indirect read permission at user level.

  • For codeunits, assign the extra indirect read permissions at user level and at object level.

  • Permissions are cumulative and not mutually exclusive.

Note Note

Record level security filters do not support wildcards. This means that you cannot use * and ? in the filters. You can use the other symbols, delimiters and, operators, such as, <, >, |, &, .., and =.

The maximum length of a security filter is 250 characters, but all of the delimiters, symbols, and operators such as, <, >, |, &, .., and = also count as characters and can considerably reduce the length of the security filters that you can enter.

Furthermore, security filters are concatenated and therefore the sum of all the security filters applied to a user or a role cannot exceed 250 characters.

See Also

Concepts

Implementing Record-Level Security
Forms, Reports, and Dataports


Applying Security Filters in a Posting Scenario

Applying Security Filters in a Posting Scenario

Applying security filters in situations where the functionality involves running one or more codeunits is quite difficult. For example, in a posting procedure the security filters are applied to the user and must then be supplemented with indirect read permissions at the user level and object level.

Setting Security Filters

The following example demonstrates how to set security filters that limit the permissions that a user has to certain functionality and illustrates the complexity of this process.

This example shows a user who can post in the G/L Journal. The user has been given the following roles.

Role | Description
All | All users
G/L-Journal | Create entries in G/L journals
G/L-Journal, Post | Post G/L journals
Payment Terms | A role created for this example that gives access to the Payment Terms table.

The first three roles are standard Microsoft Dynamics NAV roles. The last role is a new role that has been created for this example. For this example, a user called TestUser has been assigned these roles.

Note Note

To complete this example you must be able to log on as two different users—TestUser who wants to post in the G/L Journal and an administrator who modifies the roles and permissions that TestUser has been assigned. The administrator has been given the SUPER role. It is also important to remember that TestUser must log off and log on every time the administrator modifies the permissions.

In this scenario, you only want TestUser to be able to post entries that relate to the Administration department (Global Dimension 1). You must therefore apply security filters to the roles you have given TestUser. You must apply these filters to all the roles that give TestUser permission to access the G/L Account and G/L Entry tables.

See Also

Tasks

How to: Set Security Filters (Example)
How to: Debug the Code


How to: Set Security Filters (Example)

How to: Set Security Filters (Example)
See Also

This topic explains how to ensure that TestUser can only post entries in the General Journal that refer to the Administration department. You will need to ensure that the Department Code field is visible in the General Journal window.

Posting an Entry in the General Journal

To post an entry in the general journal

  1. Log on to the database as TestUser, open the General Ledger, and then click General Journals to open the General Journal window.

  2. In the Batch Name field, select CASH and enter the information that you want to post. Remember to select ADM in the Department Code field.

    If the Department Code field is not visible, click View, and then click Show Column to open the Show Column window. Select the Department Code field.

  3. Click Posting, Post (F11) to post the entry. You receive an error message informing you that you do not have read permission to the G/L Entry table.

    This occurs because each time you post a new entry it must be given a unique ID. Before this ID can be created, the ID of the last record in the G/L Entry table must be known. If the last entry in the table is not part of the ADM department, TestUser is not allowed to read it. If the last record is part of the ADM department, TestUser would be able to read it and would not receive this error message.

    To resolve this error, you must give TestUser indirect read permission to the entire G/L Entry table as described in the following procedure.

To give the user indirect read permission

  1. Log on to the database as the administrator.

  2. Create a new role that only contains permission to indirectly read from the G/L Entry table.

  3. Assign the new role to TestUser.

  4. Synchronize the security system.

  5. Log on to the database as TestUser and try to post the entry again.

    Unfortunately, you receive the same error message that you do not have read permission to the G/L Entry table. This occurs because the functionality of the form requires it to run a few codeunits and one or more of these codeunits needs to be able to read all the records in the G/L Entry table. To identify which codeunits are causing the error, you must use the Debugger to debug the code as the form is run.

    You must therefore give TestUser permission to run the Debugger.

  6. Create an extra role that only contains this permission and give it to TestUser.

  7. Remember to synchronize the security system after altering the permission system.

See Also

Tasks

How to: Debug the Code


How to: Debug the Code

How to: Debug the Code

In this topic you will learn how to debug the code and identify the codeunits that generate an error.

Debugging the Code

To debug the code

  1. Log on to the database as TestUser and open the General Journal window.

  2. In the Batch Name field, select CASH and enter the information that you want to post. Remember to select ADM in the Department Code field. Do not post the entry yet.

  3. Click Tools, click Debugger, and then click Breakpoint on Triggers to clear the check mark from this option. The debugger will only stop when the code encounters an error.

  4. Click Tools, click Debugger, and then click Active to activate the Debugger.

  5. In the General Journal window, click Posting, and then click Post.

The application runs slower now because the Debugger is running in the background.

After a while the Debugger opens and shows you where it encountered the first error.

In the Debugger window you can see that the first error occurred in codeunit 13, Gen. Jnl.-Post Batch when the code tried to read the last record, FINDLAST in the G/L Entry table.

To solve this, you must give codeunit 13 permission to read all the records in the G/L Entry table.

Giving Permission to the Codeunit

To give permission to the codeunit

  1. In the Object Designer, open codeunit 13, Gen. Jnl.-Post Batch, and open the Properties window.

  2. In the Value field of the Permissions property, click the AssistButton to open the Permissions window for the codeunit.

  3. Add the G/L Entry table to the list and ensure that the codeunit only has read permission to this table.

  4. Click OK to commit the changes that you have made in this window.

  5. Close, save, and compile the codeunit.

You do not need to synchronize the security system after altering the properties of the codeunit as it is not part of the permission system.

Now log on to the database as TestUser, activate the Debugger and try to post the entry again. The code encounters another error.

In the Debugger window, you can see that the error occurred in codeunit 12, Gen. Jnl.-Post Line when the code tried to read the last record, FINDLAST in the G/L Entry table.

To solve this, you must repeat the procedure described earlier and give codeunit 12, Gen. Jnl.-Post Line permission to read all the records in the G/L Entry table.

Log on to the database as TestUser, activate the Debugger, and try to post the entry again. This time the entry posts correctly.

Turn off the Debugger and try to post an entry for another department. You will receive a different error message informing you that you do not have write permission to the G/L Entry table. This means that your security filters work and you can only post entries for the ADM department.

See Also

Tasks

How to: Set Security Filters (Example)


Security Filters and Complex Forms

Security Filters and Complex Forms

C/SIDE does not apply record level security filters to user defined global and local variables. If your application contains complex forms that use variables to access tables containing sensitive data, the security filters that you set will not be applied to these variables. To ensure that users cannot access the sensitive data, you must modify the code that these forms contain.

By using security filters, you can ensure that a user can only post to a certain department, for example. For more information, see Applying Security Filters in a Posting Scenario. However, you should also use filters to ensure that the user can only read data from certain departments. The topics in this section describe how to limit a user's access to read data from other departments.

See Also

Tasks

How to: Check Security Filters on Forms
How to: Add Code to Forms to Support Security Filters


How to: Check Security Filters on Forms

How to: Check Security Filters on Forms

In this topic you will investigate whether a user can read data from other departments.

You will log on to the database as TestUser and open forms in the General Ledger to check if data is displayed.

To check read access to forms

  1. In the General Ledger, click Chart of Accounts to open the Chart of Account window. This window only shows data for the ADM department.

  2. In the Chart of Account window, click Balance, and then click G/L Balance by Dimension to open the G/L Balance by Dimension window.

    This is a matrix form that displays a summary of the balances for all the accounts in the chart of accounts. The list of balances can be presented in several ways by applying different filters. In this window, you select the different dimensions that you use to filter the data displayed in the G/L Balance by Dimension window.

  3. Select Department and click OK to return to the G/L Balance by Dimension window. This window now displays three totals—one for each department.

    Unfortunately, TestUser is only supposed to be able to see the total for the Administration department.

  4. In the Total Amount field for the Sales department, click the AssistButton to open the General Ledger Entries window.

    This window is empty which means that some of the security filters you have implemented are being applied and TestUser cannot see the G/L entries for the other departments.

However, TestUser is not supposed to be able to see all the totals in the G/L Balance by Dimension window. You will need to review the code that this form contains to see if there are any places where the code should be improved so that it can support security filters.

For more information about how to add code to ensure that users cannot access secure data, see How to: Add Code to Forms to Support Security Filters.

See Also

Tasks

How to: Add Code to Forms to Support Security Filters

Concepts

Security Filters and Complex Forms


How to: Add Code to Forms to Support Security Filters

How to: Add Code to Forms to Support Security Filters

To ensure that TestUser cannot access secure data, you must modify the code in the General Ledger forms.

This topic explains how to edit the code on these forms.

To add code to support security filters on forms

  1. Log on to the database as an administrator and open the G/L Balance by Dimension window.

  2. Click CTRL+F2 to open the form in Form Designer.

  3. Click View, and then click C/AL Globals to open the C/AL Globals window.

    This window contains a global variable called GLAcc that refers to the G/L Account table.

  4. Click View, and then click C/AL Code to open the C/AL Editor and see the code that the form contains.

    The first line of code in the OnOpenForm trigger is: GLAcc.SETPERMISSIONFILTER;

    This ensures that any security filters that have been set up for the current user are applied to this global variable in the code. However, the matrix form here contains functionality that allows you to change the filters that are used on the data. This means that the filters are cleared and reset. Furthermore, the C/AL language contains a function called RESET that is used to clear any filters that are set so that new filters can be set.

    With this in mind, it might be a good idea to see if the code in the G/L Balance by Dimension form uses the RESET function.

  5. Use the Find window to locate all the places where the RESET function is called. It occurs in two places—in the SetCommonFilters function and in the CalcAmount function. Both of these are user-defined functions.

  6. Look at the local variables that have been declared for these functions.

    The SetCommonFilter function contains a parameter that calls the G/L Account table by reference.

  7. Look at the code in these functions. In the CalcAmount function, after the code calls the RESET function on the GLAcc global variable, it calls the SetCommonFilters function. All of this suggests that the instance of the RESET function that is most relevant is the one that occurs in the SetCommonFilters function.

  8. Enter the following code immediately after the RESET function in the SetCommonFilters trigger: GLAcc.SETPERMISSIONFILTER;

  9. Close, save, and compile the form.

  10. Log on to the database again as TestUser and open the G/L Balance by Dimension window. Remember to select Department in the Show as Lines field.

    The form no longer displays data that belongs to the other departments.

You have now successfully implemented record level security for posting and ensured that the user only has read access to the data specified by their security filters.

See Also

Tasks

How to: Check Security Filters on Forms


Reference

This section provides reference information for Microsoft Dynamics NAV 2009 objects. For more reference information, see C/SIDE Reference Guide.

See Also

Reference

C/SIDE Specifications and Limitations

Concepts

C/SIDE Reference Guide

Other Resources

Special C/SIDE Tables


C/SIDE Reference Guide

C/SIDE Reference Guide

The topics in this section contain help on all functions, data types, properties, and triggers in C/SIDE. They also provide general descriptions of some of the features and functionality that C/SIDE supports.

In the Table of Contents, all C/AL functions are grouped alphabetically according to the data type that they support or according to a category. Each data type topic contains a description of the data type.

Properties and triggers are also listed alphabetically.

For more information about the C/SIDE development environment, see Getting Started.

To ensure that you are reading the latest information and to find additional Microsoft Dynamics NAV 2009 documentation, visit the MSDN Library. To download the latest version of the C/SIDE Reference Guide, visit the Microsoft Download Center.


C/AL Functions

C/AL Functions

The C/AL functions in this section are grouped alphabetically according to the data type that they support or according to a category. Each data type topic contains a description of the data type.

  • Automation Data Type

  • Binary Data Type

  • BLOB Data Type

  • Boolean Data Type

  • Char Data Type

  • Codeunit Data Type

  • Controls

  • Database

  • Dataport Data Type

  • DateFormula Data Type

  • Dates and Times

  • Dialog Data Type

  • Error Handling

  • FieldRef Data Type

  • File Data Type

  • Form Data Type

  • GUID Data Type

  • InStream and OutStream Data Types

  • Key Groups

  • KeyRef Data Type

  • Numbers

  • OCX Data Type

  • Option Data Type

  • Page Data Type

  • Record Data Type

  • RecordID Data Type

  • RecordRef Data Type

  • Report Data Type

  • Strings

  • System

  • TableFilter Data Type

  • Variant Data Type

  • XMLport Data Type


Automation Data Type

Automation Data Type

Use the Automation data type to reference an automation server. In order to use an automation server in C/SIDE, define a variable of type Automation and give it a name. Next, click the AssistButton in the Subtype field. In the Automation Object List form that opens, use the AssistButton in the Automation Server field to get a list of available automation servers. Select a server and then click OK. When the lookup form closes, the table part of the Automation Object List form is filled in with the interfaces of the selected automation server. Select an interface and then click OK.

This procedure has selected the GUID of the automation server, the version number, and the GUID of the interface. It is immediately evaluated into a name such as <name of server>.<name of interface>, as in the following:

CopyCode image Copy Code
'Microsoft Excel X.0 Object Library'.Application

When you have defined an automation server as a variable, you must use CREATE Function (Automation) to create an instance of the server. After that, you can use the server through the variable. You can browse its methods and properties in the Symbol menu.

When you are using a server, you should know that there is not a one-to-one relationship between C/AL data types and COM data types. For an overview of the data type mapping, see Using COM Technologies in C/SIDE.

C/SIDE can receive events from an automation server.

If you use a variable of type Automation to automate Microsoft Excel and you run an English (United States) version of Excel but the regional settings for the computer are configured for a non-English language, then you will receive the following error:

CopyCode image Copy Code
Error: 0x80028018 (-2147647512)
Description: Old Format or Invalid Type Library

For more information, see Microsoft Help and Support article 320369: BUG: "Old format or invalid type library" error when automating Excel.

Expand image See Also

Reference

CREATE Function (Automation)
ISCLEAR Function (Automation)
Variant Data Type


CREATE Function (Automation)

CREATE Function (Automation)
See Also
CollapseAll image

Creates an Automation object.

[Ok :=] CREATE(Automation [,NewServer] [,OnClient])

Parameters

Automation

Type: Automation

A variable that has previously been declared.

NewServer

Type: Boolean

If NewServer is false (the default), CREATE will try to reuse an already running instance of the automation server referenced by Automation before creating a new instance. If NewServer is true, CREATE will always create a new instance of the automation server.

OnClient

Type: Boolean

If OnClient is false (the default), then the Automation object is created on the Microsoft Dynamics NAV Server. If OnClient is true, then the Automation object is created on the client.

This parameter is only valid when you run the function on the RoleTailored client. On the Classic client, the Automation object is always created on the client.

Expand image Property Value/Return Value

Type: Boolean

true if the Automation object could be created; otherwise, false.

If the return is not tested, execution will terminate with a run-time error.

Expand image Remarks

CREATE creates (instantiates) the automation server referenced by the Automation variable. While an OCX (custom control) is instantiated implicitly, Automation variables must be created explicitly.

If you have an array of OCXs, each control will be created when its first member is accessed.

If you have an array of automation servers, you have to call CREATE on each element individually. The NewServer variable can be used independently on each element.

The automation object that is created can be explicitly destroyed by the CLEAR Function. The object will be destroyed implicitly when the Automation variable goes out of scope.

An Automation variable can only be created once. You will get a run-time error if you try to create an Automation a second time, without calling CLEAR first. You will also get a run-time error if you try to create an OCX variable.

Expand image See Also

Reference

Automation Data Type


ISCLEAR Function (Automation)

ISCLEAR Function (Automation)
See Also Example
CollapseAll image

Checks whether an automation object has been created or cleared.

Ok := ISCLEAR(Automation)

Parameters

Automation

Type: Automation

A variable that has previously been declared.

Expand image Property Value/Return Value

Type: Boolean

true if any of the following is true; otherwise, false:

  • The automation variable has not been created. See CREATE Function (Automation).

  • The automation variable has been cleared. See CLEAR Function.

  • The automation variable has been assigned NULL by an automation server.

Expand image Example

The following is an example of how you can use the ISCLEAR function. This example requires that you create the following variables.

Name | DataType | Subtype
Document | Automation | 'Microsoft XML, V3.0'.DOMDocument
ReturnValue | Boolean |
CopyCode image Copy Code
ReturnValue := ISCLEAR(Document);
// ReturnValue will be TRUE.
CREATE(Document);
ReturnValue := ISCLEAR(Document);
// ReturnValue will be FALSE.
CLEAR(Document);
ReturnValue := ISCLEAR(Document);
// ReturnValue will be TRUE.

Expand image See Also

Reference

Automation Data Type


Binary Data Type

Binary Data Type

The BINARY data type, used in previous versions of Microsoft Dynamics NAV to store fixed lengths of binary data in a record, is removed from Microsoft Dynamics NAV 2009. If you previously used the BINARY data type, consider using the BLOB Data Type instead.


BLOB Data Type

BLOB Data Type

A binary large object (BLOB) is a complex data type. Variables of this data type differ from normal numeric and string variables in that BLOBs have a variable length.

The maximum size of a BLOB is normally determined by your system's disk storage capacity. However, the maximum size in C/SIDE is 2 GB.

Expand image Remarks

Use BLOBs to store memos (text), pictures (bitmaps), or user-defined types.

Note Note

C/SIDE cannot display text stored in BLOBs.

You can read from and write to BLOBs by creating input and output streams, respectively. To do so, use CREATEINSTREAM Function (BLOB) and CREATEOUTSTREAM Function (BLOB).

For more information, see InStream and OutStream Data Types.

To optimize performance, when you access a record that has a BLOB field, the data in the BLOB is not always read into memory. To be sure that the BLOB data is in memory, you can call the CALCFIELDS Function (Record) on the BLOB to calculate the BLOB before you use it in C/AL or display it in the application.

It is not supported to insert a BLOB field into a Variant.

Differences Between the Classic Client and RoleTailored Client

In the Classic client, a control on a form can have a SourceExpr that specifies a BLOB field from a table other than the SourceTable for the form. In the RoleTailored client, this is not supported. One way to access a BLOB from a page in the RoleTailored client is to add a BLOB field to the SourceTable of the page and assign the BLOB field from the original table to the new field value.

Expand image See Also

Reference

CREATEINSTREAM Function (BLOB)
CREATEOUTSTREAM Function (BLOB)
EXPORT Function (BLOB)
HASVALUE Function (BLOB)
IMPORT Function (BLOB)
Variant Data Type


CREATEINSTREAM Function (BLOB)

CREATEINSTREAM Function (BLOB)
See Also
CollapseAll image

Creates an InStream object for a binary large object (BLOB). This enables you to read data from the BLOB.

Blob.CreateInStream(Stream)

Parameters

Blob

Type: Variable

The BLOB variable for which you are creating the InStream object.

Stream

Type: InStream

The InStream object type that has been created.

Expand image Remarks

For more information, see the following:

  • InStream and OutStream Data Types

  • Code Example for Streams.

Expand image See Also

Reference

BLOB Data Type


CREATEOUTSTREAM Function (BLOB)

CREATEOUTSTREAM Function (BLOB)
See Also
CollapseAll image

Creates an OutStream object for a binary large object (BLOB). This enables you to write data to the BLOB.

Blob.CreateOutStream(Stream)

Parameters

Blob

Type: Variable

The BLOB variable for which you are creating the OutStream object.

Stream

Type: OutStream

The OutStream object type that has been created.

Expand image Remarks

For more information, see the following:

  • InStream and OutStream Data Types

  • Code Example for Streams.

Expand image See Also

Reference

BLOB Data Type


EXPORT Function (BLOB)

EXPORT Function (BLOB)
See Also
CollapseAll image

Exports a binary large object (BLOB).

[ExportName] := Blob.EXPORT([Name [, CommonDialog]])

Parameters

Blob

Type: Variable

The BLOB that you want to export.

Name

Type: Text or code

The path and name of the BLOB that you want to export.

When you enter the path, keep in mind these shortcuts:

  • You can omit the drive letter if the command is located on the current drive.

  • You can omit the full path if the command is located in the current directory.

  • You can enter only the subdirectory name if the command is located in a subdirectory of the current directory.

CommonDialog

Type: Boolean

Specifies whether you want to display a dialog box before the BLOB is exported. This dialog box lets you select the file you want to export. Based on the SubType Property property, only the appropriate file types are listed, such as bitmap files (*.bmp), memo files (*.txt), or all files (*.*).

If the CommonDialog parameter is true, the system will display the confirmation dialog box. If the CommonDialog parameter is false (default), the system will not display the confirmation dialog box.

Expand image Property Value/Return Value

Type: text

The name and path of the file the system imported.

If the return value is the file's name and path, the BLOB was exported

If the return value is blank, the BLOB was not exported.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Reference

BLOB Data Type


HASVALUE Function (BLOB)

HASVALUE Function (BLOB)
See Also
CollapseAll image

Determines whether a binary large object (BLOB) has a value.

HasValue := Blob.HASVALUE

Parameters

Blob

Type: BLOB

The BLOB that you want to check.

Expand image Property Value/Return Value

Type: Boolean

true if the BLOB has a value; otherwise, false.

Expand image See Also

Reference

BLOB Data Type


IMPORT Function (BLOB)

IMPORT Function (BLOB)
CollapseAll image

Imports a binary large object (BLOB).

[ImportName] := Blob.IMPORT([Name [, CommonDialog]])

Parameters

Blob

Type: Variable

The BLOB that you want to import.

Name

Type: Text or code

The path and name of the BLOB that you want to import.

When you enter the path, keep in mind the following shortcuts:

  • You can omit the drive letter if the command is located on the current drive.

  • You can omit the full path if the command is located in the current directory.

  • You can enter only the subdirectory name if the command is located in a subdirectory of the current directory.

CommonDialog

Type: Boolean

Specifies whether you want to display an import dialog box before the BLOB is imported. This dialog box lets you select the file that you want to import. Based on the SubType Property, only the appropriate file types are listed, such as bitmap files (*.bmp), memo files (*.txt), or all files (*.*).

If the CommonDialog parameter is true, then the import dialog box is displayed. If the CommonDialog parameter is false (default), then the import dialog box is not displayed.

Expand image Property Value/Return Value

Type: text

The name and path of the file that the system imported.

If the return value is the file's name and path, the BLOB was imported.

If the return value is blank, the BLOB was not imported.

Expand image Remarks

This function is not supported in the RoleTailored client.


Boolean Data Type

Boolean Data Type

Use this simple data type to indicate one of two values: true or false.

For usability reasons, Boolean values are sometimes shown as Yes or No. For instance, for the form property InsertAllowed, the two possible values are Yes or No.


Char Data Type

Char Data Type
See Also Example
CollapseAll image

Use this simple data type to store a single character as a value in the range 0 to 255. You can easily convert this data type from a number to a character and vice versa. This means you can use mathematical operators on char variables as well as numeric variables.

Expand image Example

You can assign a constant string of the length 1 to a char variable, as shown in the first line of the following code example.

You can assign a single char in a text, code, or binary variable to a char variable, as shown in the second line of the following code example.

You can assign a numeric value to a char variable as shown in the third line of the following code example. This causes the char variable to contain the character from the ASCII character set that corresponds to the numeric ASCII code.
CopyCode image Copy Code
C := 'A';
C := S[2];
C := 65;

Expand image Differences Between the Classic Client and RoleTailored Client

In the Classic client, you can assign a char to any position within the defined length of a text or code variable. For example, if the value of the text variable MyText is 'abc' then you can use the following assignment.

CopyCode image Copy Code
MyText[5] := 'e';

In this case, MyText is displayed as 'abc' because the null terminator is at position 4 in MyText and signifies the end of the text string. You can then use the following assignment.

CopyCode image Copy Code
MyText[4] := 'd';

Now MyText is displayed as 'abcde' and the null terminator of the string is at position 6 in MyText.

In the RoleTailored client, you cannot assign a char to a position greater than the position of the null terminator. For example, if the value of the text variable MyText is 'abc', then the null terminator is at position 4 and the following assignment causes a run-time error to occur.

CopyCode image Copy Code
MyText[5] := 'e';

Expand image See Also

Reference

Text Data Type
Code Data Type


Codeunit Data Type

Codeunit Data Type

Use this complex data type to store units of C/AL code. Codeunits contain a number of user-defined functions.

Expand image See Also

Reference

Codeunit.RUN Function (Codeunit)
RUN Function (Codeunit)


Codeunit.RUN Function (Codeunit)

Codeunit.RUN Function (Codeunit)
See Also Example
CollapseAll image

Loads and executes the unit of C/AL code you specify. See also RUN Function (Codeunit).

[Ok :=] Codeunit.RUN(Number[, Record])

Parameters

Number

An integer data type that identifies the unit of C/AL code. You can use the Symbols option on the View menu to choose from a list.

If the codeunit you specify does not exist, a run-time error occurs.

If you run the codeunit with a record from a table other than the one it is associated with, a run-time error occurs.

Record

This optional parameter identifies a record. This parameter is a record data type.

Expand image Property Value/Return Value

Type: Boolean

If you do not include the optional return value and an error occurs while the codeunit is running, the C/AL code that called this codeunit will terminate.

If you include the return value and an error occurs, the calling C/AL code continues to run. This means that you must handle any errors.

true if no errors occurred; otherwise, false.

Expand image Example

CopyCode image Copy Code
Codeunit.RUN(4711, SomeRecord);

Expand image See Also

Reference

Codeunit Data Type


EXPORTOBJECTS Function (Codeunit, Dataport, Form, MenuSuite, Page, Report, Table, XMLport)

EXPORTOBJECTS Function (Codeunit, Dataport, Form, MenuSuite, Page, Report, Table, XMLport)
See Also Example
CollapseAll image

Exports one or more objects to either a text file or an .xml file.

EXPORTOBJECTS(FileName, ObjectTableRecord[, Format])

Parameters

FileName

Type: Text

The path and name of the file to which you export objects.

ObjectTableRecord

Type: Record

Specifies a record in the Object table, which is table 2000000001. You can set filters on this record so that the exported objects are also filtered. For more information, see SETFILTER Function (Record).

Format

Type: Integer

The type of the file to which you export objects. The valid values are 0 and 1. If you specify 0, then the data is exported in text format. If you specify 1, then the data is exported in XML format. The default value is 0.

Expand image Remarks

This function is not supported on Microsoft Dynamics NAV Server.

This function achieves the same result as the Export item on the File menu in the Classic client.

Exporting to an .xml file is only supported for form or page objects.

For more information about file handling best practices, see File Handling.

Expand image Example

This example filters all reports in the range 50000 to 60000 and then exports the filtered set of reports to a text file. This example requires that you create the following variable.

Variable | Data type | Subtype
MyFilter | Record | Object
CopyCode image Copy Code
MyFilter.SETFILTER(MyFilter.Type,'=Report');
MyFilter.SETFILTER(MyFilter.ID,'%1..%2',50000,60000);
EXPORTOBJECTS('C:\MyExport.txt', MyFilter, 0);

Expand image See Also

Reference

IMPORTOBJECTS Function (Codeunit, Dataport, Form, MenuSuite, Page, Report, Table, XMLport)


IMPORTOBJECTS Function (Codeunit, Dataport, Form, MenuSuite, Page, Report, Table, XMLport)

IMPORTOBJECTS Function (Codeunit, Dataport, Form, MenuSuite, Page, Report, Table, XMLport)
See Also Example
CollapseAll image

Imports one or more objects from either a text file or an .xml file to the application.

IMPORTOBJECTS(FileName[, Format])

Parameters

FileName

Type: Text

The path and name of the file from which you import objects.

Format

Type: Integer

The type of the file from which you import objects. The valid values are 0 and 1. If you specify 0, then the file that you specify in the FileName parameter must be a text file. If you specify 1, then the file that you specify in the FileName parameter must be an .xml file. The default value is 0.

Expand image Remarks

This function is not supported on the RoleTailored client.

This function achieves the same result as the Import item on the File menu in the Classic client.

After you import an object with this function, the object is not compiled. To run the object, you must first manually compile it.

For more information about file handling best practices, see File Handling.

Expand image Example

This example imports an .xml file that contains page objects.

CopyCode image Copy Code
IMPORTOBJECTS('C:\MyExport.txt', 1);

Expand image See Also

Reference

EXPORTOBJECTS Function (Codeunit, Dataport, Form, MenuSuite, Page, Report, Table, XMLport)


RUN Function (Codeunit)

RUN Function (Codeunit)
See Also Example
CollapseAll image

Loads and executes the unit of C/AL code you specify. To use this function, you can specify a C/SIDE table associated with the codeunit when you defined the codeunit properties. This allows you to pass a variable with the function. The transaction that the codeunit contains is always committed due to the Boolean return value.

[Ok :=] Codeunit.RUN(VAR Record)

Parameters

Codeunit

Type: Codeunit

Identifies the unit of code you want to run.

VAR Record

Type: Record

This parameter is not always optional. If you specify a C/SIDE table associated with the codeunit, you can select a record. If you do not specify a table, you cannot specify a record. However, you must use this parameter to select a record if you attached a record to the codeunit when you defined its properties.

This parameter is a record data type.

Expand image Property Value/Return Value

Type: Boolean

If you do not include the optional return value and an error occurs while the codeunit is running, the C/AL code that called this codeunit will terminate.

If you include the return value and an error occurs, the calling C/AL code continues to run. This means that you must handle any errors. If you include the return value, the variables used in the codeunit will be cleared before and after the codeunit runs.

true if no errors occurred; otherwise, false.

Expand image Example

CopyCode image Copy Code
VARc : CodeUnit1,c.XXX(expression1, ...); // any user-defined function c.RUN(Rec)

Expand image See Also

Reference

Codeunit Data Type


Controls

Controls

This section contains the following topics:

  • Matrix Box

  • ACTIVATE Function (Control)

  • DECIMALPLACESMAX Function (Control)

  • DECIMALPLACESMIN Function (Control)

  • EDITABLE Function (Control, Form)

  • ENABLED Function (Control)

  • HEIGHT Function (Control, Form)

  • INLINEEDITING Function (Matrix Box,Table Box)

  • UPDATEEDITABLE Function (Control, Form)

  • UPDATEFONTBOLD Function (Control)

  • UPDATEFORECOLOR Function (Control)

  • UPDATEINDENT Function (Text Box)

  • UPDATESELECTED Function (Control)

  • VISIBLE Function (Control, Form)

  • WIDTH Function (Control, Form)

  • XPOS Function (Control, Form)

  • YPOS Function (Control, Form)


Matrix Box

Matrix Box

A matrix box is a composite control that can show information from several tables at the same time. The first two tables are the vertical and the horizontal table of the matrix box control. In the matrix part of the control, each cell can be used to display information that is calculated on the basis of fields in these two tables, or information that is retrieved from other tables (with values from the first two tables being used to select records, for example by setting filters). Each cell in the matrix is the intersection of a record from the vertical and the horizontal table.

The part to the left of the vertical divider bar displays records from the vertical table, the table that is the source table of the form, similar to a table box. To the right of the divider bar is the matrix itself. Above it, the records from the horizontal table are displayed (in the style that is normally used for the labels in a table box). This is the matrix heading. The horizontal table is called the matrix source table.

Note Note

Matrix box controls are not supported in the RoleTailored client.

The following illustration shows a matrix box control on Form 113, Budget.

Matrix box section of Form 113, Budget

Expand image Navigating in a Matrix Box

Navigating in a matrix box is more complex, since there are several tables and dimensions involved. The following describes how to navigate by using the mouse and by using the keyboard.

Using the Mouse

You can scroll the vertical table vertically by clicking the navigation buttons to the right of the matrix. You can scroll the horizontal table horizontally by clicking the navigation buttons at the bottom of the matrix. If all columns of the vertical table do not fit in the "table box", a normal scroll bar will be added, and you can scroll the columns horizontally, similar to a table box.

You can resize any column by placing the cursor in the label area and then dragging when the cursor changes to the resize cursor (which it does when it is on top of a column divider). Dragging the vertical divider bar changes the relative proportions of the table box and matrix box parts.

The height of the headings, both in the table box and the matrix part of the control, can be adjusted by dragging. The columns in the table box part can be resized vertically.

Using the Keyboard

To use the keyboard for navigation, you will have to place the focus in the part of the control that you want your keystrokes to affect.

You can move from one part of the control to another by pressing CTRL+<arrow key>. The following table shows how to move from one part of the control to another.

Keyboard shortcut | Description
CTRL+RIGHT ARROW | Move from the table box to the matrix
CTRL+UP ARROW | Move from the matrix to the matrix heading
CTRL+DOWN ARROW | Move from the matrix heading back to the matrix
CTRL+LEFT ARROW | Move from the matrix to the table box

You cannot go directly from the matrix heading to the table box (you have to go via the matrix).

When the focus is in the matrix heading, use PAGE UP and PAGE DOWN to scroll the horizontal table (that is, a horizontal scroll).

CTRL+PAGE UP or CTRL+PAGE DOWN in the matrix part (including the matrix heading) will also scroll the horizontal table.

Expand image Creating a Matrix Box

The following procedure describes how to create a matrix box in which both the vertical and the horizontal tables are based on the Integer table and the matrix cells display the product of the two integers in the records that intersect at that cell.

To create a matrix box

  1. Create a new form, and select the Integer table as the source table.

  2. Add a matrix box to the form. Give the matrix box control a name by setting the Name Property. Set the HorzGlue Property and VertGlue Property to Both.

  3. Insert a text box with the Number field from the Integer record as the source expression in the table part of the matrix box.

  4. In the property sheet of the matrix box control, select Integer as the MatrixSourceTable Property.

  5. Add a text box without a source expression to the empty part of the matrix box control. Verify that the InMatrix Property of this text box is Yes.

  6. Add a text box without a source expression to the last empty part (the matrix heading) of the matrix box control. Verify that the InMatrixHeading Property of this text box is Yes.

  7. Add a source expression to the text box in the matrix heading, which you added in Step 6. The source expression should point to a field from the MatrixSourceTable. The following example of a source expression is for a matrix box named Matrix in which the horizontal table is the Integer table:

    CopyCode image Copy Code
    CurrForm.Matrix.MatrixRec.Number

  8. Add a source expression to the text box in the matrix. The following example of a source expression will display the product of two integers:

    CopyCode image Copy Code
    Number * CurrForm.Matrix.MatrixRec.Number

Expand image Programming Information

To access the horizontal table (the matrix source table), you must give the matrix box control a name by setting the Name property of the control.

When the matrix box control has a name, the records of the table can be accessed by using the following:

CopyCode image Copy Code
CurrForm.<name of matrix box control>.MatrixRec.<field>

Triggers

A matrix box control has the following triggers:

  • OnFindRecord Trigger

  • OnNextRecord Trigger

  • OnAfterGetRecord Trigger

  • OnAfterGetCurrRecord Trigger

  • OnBeforePutRecord Trigger

  • OnNewRecord Trigger

  • OnInsertRecord Trigger

  • OnModifyRecord Trigger

  • OnDeleteRecord Trigger

Properties

A matrix box has the following properties:

  • ID Property

  • Name Property

  • XPos Property

  • YPos Property

  • Width Property

  • Height Property

  • HorzGlue Property

  • VertGlue Property

  • Visible Property

  • Enabled Property

  • Editable Property

  • Focusable Property

  • ParentControl Property

  • InFrame Property

  • InPage Property

  • BackColor Property

  • Border Property

  • BorderColor Property

  • BorderStyle Property

  • BorderWidth Property

  • RowHeight Property

  • MatrixColumnWidth Property

  • HeadingHeight Property

  • ToolTip Property

  • InlineEditing Property

  • Description Property

  • MatrixSourceTable Property

The following text box properties are special for text boxes that are part of a matrix box control:

  • InMatrix Property

  • InMatrixHeading Property

Areas

  • (% MAT_VERT "Vertical table") This area contains records from the vertical table. The vertical table is the table that is the source table of the form.

  • (% MAT_HORZ "Horizontal table") This area contains records from the horizontal table. The horizontal table is the table that is the matrix source table. This area is also known as the matrix heading.

  • (% MAT_MAT "Matrix") This area is the matrix itself. Each cell is at the intersection of a record from the vertical table and one from the horizontal table.

  • (% MAT_NV "Vertical navigation") Use the navigation buttons in this area to scroll the vertical table.

  • (% MAT_NH "Horizontal navigation") Use the navigation buttons in this area to scroll the horizontal table.

  • (% MAT_SCROLL "Scroll bar") Use this scroll bar to see other records from the vertical table.

Expand image See Also

Reference

SourceTable Property


ACTIVATE Function (Control)

ACTIVATE Function (Control)
See Also
CollapseAll image

Makes a control active. This function applies to command buttons, menu buttons, check boxes, option buttons, text boxes, picture boxes, indicators, and subform controls.

[Ok := ] Control.ACTIVATE

Expand image Property Value/Return Value

Type: Boolean

Expand image Remarks

This function is not supported in the RoleTailored client.

A control becomes active when you click on it or select it by any other means such as by using the keyboard. This function provides another way to make active a control that is already displayed on the screen.

When you call this function on a control, the control becomes the active control on the form. If the control is already active, the control is given focus. If the control is not active, it is given focus the next time the form is activated. You must load the form before you can activate its controls.

Expand image See Also

Concepts

Controls


DECIMALPLACESMAX Function (Control)

DECIMALPLACESMAX Function (Control)
See Also
CollapseAll image

Returns the current setting of the maximum number of decimal places for a control (field or text box), and sets a new value. The function manipulates the maximum number-part of the setting of the DecimalPlaces Property property.

[CurrMaxDecimals] := DECIMALPLACESMAX([NewMaxDecimals])

Parameters

NewMaxDecimals

Type: Integer

The new setting of the maximum number of decimal places.

Expand image Property Value/Return Value

Type: Integer

The current setting of the maximum number of decimal places.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Concepts

Controls


DECIMALPLACESMIN Function (Control)

DECIMALPLACESMIN Function (Control)
See Also
CollapseAll image

Returns the current setting of the minimum number of decimal places for a control (field or text box), and sets a new value. The function manipulates the maximum number-part of the setting of the DecimalPlaces Property property.

[CurrMinDecimals] := DECIMALPLACESMIN([NewMinDecimals])

Parameters

NewMinDecimals

Type: Integer

The new setting of the minimum number of decimal places.

Expand image Property Value/Return Value

Type: Integer

The current setting of the minimum number of decimal places.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Concepts

Controls


EDITABLE Function (Control, Form)

EDITABLE Function (Control, Form)
See Also
CollapseAll image

Returns the current setting of the Editable Property and changes the setting of the property.

[IsEditable] := Form.EDITABLE([SetEditable])

Parameters

SetEditable

Type: Boolean

The new setting of the Editable Property.

Expand image Property Value/Return Value

Type: Boolean

The current value of the Editable Property.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Reference

Form Data Type

Concepts

Controls


ENABLED Function (Control)

ENABLED Function (Control)
See Also
CollapseAll image

Returns the current setting of the Enabled Property of a control, and changes the setting of the property.

[IsEnabled] := ENABLED([SetEnabled])

Parameters

SetEnabled

Type: Boolean

The new setting of the Enabled Property.

Expand image Property Value/Return Value

Type: Boolean

The current value of the Enabled Property.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Concepts

Controls


HEIGHT Function (Control, Form)

HEIGHT Function (Control, Form)
See Also
CollapseAll image

Returns the current setting of the Height Property of a form or control, and sets this property to a new value.

[CurrHeight] := Form.HEIGHT([NewHeight])

Parameters

NewHeight

Type: Integer

The new setting of the Height Property.

Expand image Property Value/Return Value

Type: Integer

The current setting of the Height Property.

Expand image Remarks

The HEIGHT function is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Concepts

Controls


INLINEEDITING Function (Matrix Box,Table Box)

INLINEEDITING Function (Matrix Box,Table Box)
See Also
CollapseAll image

Returns the current setting of the InlineEditing Property of a table box or a matrix box, and changes the setting of the property.

[IsInLineEditing] := INLINEEDITING([SetInLineEditing])

Parameters

SetInLineEditing

Type: Boolean

The new setting of the InlineEditing Property.

Expand image Property Value/Return Value

Type: Boolean

The current value of the InlineEditing Property.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Concepts

Controls


UPDATEEDITABLE Function (Control, Form)

UPDATEEDITABLE Function (Control, Form)
See Also Example
CollapseAll image

Dynamically changes the setting of the Editable Property of a field, form, or control.

UPDATEEDITABLE(Editable)

Parameters

Editable

Type: Boolean

Possible values are true and false. If the value is true, the control will be changed to editable. If the value is false, the control will be changed to not editable.

Expand image Remarks

This function is not supported in the RoleTailored client.

This function can only be called from the OnBeforeInput Trigger of the control. The property will only be changed temporarily, that is, for the duration of this form.

Expand image Example

In this example, you use this function to set the Editable Property of a control dynamically, based on, for example, the current value of another field.
CopyCode image Copy Code
IF "On Hold" THEN
  CurrForm.Address.UPDATEEDITABLE(FALSE);

Expand image See Also

Reference

Form Data Type

Concepts

Controls


UPDATEFONTBOLD Function (Control)

UPDATEFONTBOLD Function (Control)
See Also Example
CollapseAll image

Dynamically changes the setting of the FontBold Property property of a control.

UPDATEFONTBOLD(FontBold)

Parameters

FontBold

Type: Boolean

Possible values are true and false. If the value is true, then the control will be shown in bold. If the value is false, then the control will not be shown in bold.

Expand image Remarks

This function is not supported in the RoleTailored client.

This function can only be called from the OnFormat Trigger trigger of the control. The property will only be changed temporarily, that is, for the duration of this form.

Expand image Example

The intended use of this function is to display controls of selected records in a tabular form by using the bold font. If a repeated control in a table box has the FontBold Property property set to yes, then all rows will be using the bold font. Using this function, you can select individual records where the bold font should be used, based on, for example, the current value of another field, like in the following code example.
CopyCode image Copy Code
IF Type = Type::Heading THEN
  CurrForm.Name.UPDATEFONTBOLD(TRUE);

Expand image See Also

Concepts

Controls


UPDATEFORECOLOR Function (Control)

UPDATEFORECOLOR Function (Control)
See Also Example
CollapseAll image

Dynamically changes the setting of the ForeColor Property property of a control.

UPDATEFORECOLOR(ForeColor)

Parameters

ForeColor

Type: Integer

Used to set the new foreground (text) color. Identifies a color by using the RGB Color Model value of the color.

Expand image Remarks

This function is not supported in the RoleTailored client.

This function can only be called from the OnFormat Trigger trigger of the control

Expand image Example

The intended use of this function is to display controls of selected records in a tabular form in a specific foreground (text) color. The color set by the ForeColor Property property causes all rows to be displayed in this color. By using this function, you can select individual records where the color should be used, based on, for example, the current value of some other field, like the following cod example.
CopyCode image Copy Code
IF Amount < 0 THEN
  CurrForm.Amount.UPDATEFORECOLOR(255);

This would display the Amount control with red as the foreground color. For detailed information about the integer value to use to specify a color, see RGB Color Model.

Expand image See Also

Concepts

Controls


UPDATEINDENT Function (Text Box)

UPDATEINDENT Function (Text Box)
See Also Example
CollapseAll image

Sets the Indent Property of a text box.

UPDATEINDENT(Indent)

Parameters

Indent

Type: Integer

The indentation in 1/100 of a millimeter.

Expand image Remarks

This function is not supported in the RoleTailored client.

The Indent Property can only be set by using this function from the OnFormat Trigger of the text box. It cannot be set from the property sheet.

The intended use is to provide some means of structuring information in a tabular form by indenting the contents of a text box, based a hierarchy. For examples of other functions that are used for similar purposes, see UPDATEFORECOLOR Function (Control) and UPDATEFONTBOLD Function (Control).

Expand image Example

You can use this function to indent a text box in a tabular form according to the value in another field.
CopyCode image Copy Code
CurrForm.Name.UPDATEINDENT(Level * 220);

The Level field contains integer values from 0 and upward. The higher this value, the more indentation is added to the text box that displays the contents of the Name field.

Expand image See Also

Concepts

Controls


UPDATESELECTED Function (Control)

UPDATESELECTED Function (Control)
See Also
CollapseAll image

Marks a control as selected. This will normally be displayed in reverse video, but it depends upon the Windows color scheme that the end-user has chosen.

UPDATESELECTED(Selected)

Parameters

Selected

Type: Boolean

Possible values are true and false. If the value is true, the control will be marked as selected. If the value is false, the selection indication will be removed from the control.

Expand image Remarks

This function is not supported in the RoleTailored client.

This function can only be used in the OnFormat Trigger trigger.

Expand image See Also

Concepts

Controls


VISIBLE Function (Control, Form)

VISIBLE Function (Control, Form)
See Also
CollapseAll image

Returns the current setting of the Visible Property of a form or control, and changes the setting of the property.

[IsVisible] := Form.VISIBLE([SetVisible])

Parameters

SetVisible

Type: Boolean

The new setting of the Visible Property.

Expand image Property Value/Return Value

Type: Boolean

The current value of the Visible Property.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Reference

Form Data Type

Concepts

Controls


WIDTH Function (Control, Form)

WIDTH Function (Control, Form)
See Also
CollapseAll image

Returns the current setting of the Width Property of a form or control, and sets this property to a new value.

[CurrWidth] := Form.WIDTH([NewWidth])

Parameters

NewWidth

Type: Integer

The new setting of the Width Property.

Expand image Property Value/Return Value

Type: Integer

The current setting of the Width Property.

Expand image Remarks

The WIDTH function is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

Form Data Type

Concepts

Controls


XPOS Function (Control, Form)

XPOS Function (Control, Form)
See Also
CollapseAll image

Returns the current setting of the XPos Property of a form or control, and sets this property to a new value.

[CurrXPos] := Form.XPOS([NewXPos])

Parameters

NewXPos

Type: Integer

The new setting of the XPos Property.

Expand image Property Value/Return Value

Type: Integer

The current setting of the XPos Property.

Expand image Remarks

The XPOS function is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

Form Data Type
YPOS Function (Control, Form)

Concepts

Controls


YPOS Function (Control, Form)

YPOS Function (Control, Form)
See Also
CollapseAll image

Returns the current setting of the YPos Property of a form or control, and sets this property to a new value.

[CurrYPos] := Form.YPOS([NewYPos])

Parameters

NewYPos

Type: Integer

The new setting of the YPos Property.

Expand image Property Value/Return Value

Type: Integer

The current setting of the YPos Property.

Expand image Remarks

The YPOS function is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

Form Data Type
XPOS Function (Control, Form)

Concepts

Controls


Database

Database

This section contains the following topics:

  • CHECKLICENSEFILE Function (Database)

  • COMMIT Function (Database)

  • COMPANYNAME Function (Database)

  • CURRENTTRANSACTIONTYPE Function (Database)

  • LOCKTIMEOUT Function (Database)

  • SELECTLATESTVERSION Function (Database)

  • SERIALNUMBER Function (Database)

  • TRANSACTIONTYPE Data Type

  • USERID Function (Database)


CHECKLICENSEFILE Function (Database)

CHECKLICENSEFILE Function (Database)
See Also
CollapseAll image

Checks a key in the license file of the system.

CHECKLICENSEFILE(KeyNumber)

Parameters

KeyNumber

Type: Integer

The number of the key you want to check.

Expand image Remarks

The license file turns on or off different system capabilities. Use this function to check a key in the file for the current user. If the user has no access rights to the object, a message is displayed and the process is terminated.

If you omit this function, the user will have the ability to continue regardless of whether the appropriate license file is open.

Expand image See Also

Concepts

Database


COMMIT Function (Database)

COMMIT Function (Database)
See Also Example
CollapseAll image

Ends the current write transaction.

Commit

Expand image Remarks

When a C/AL codeunit begins, it automatically enables write transactions to be performed. When a C/AL code module completes, it automatically ends the write transaction by committing the updates made by the C/AL code.

This means that if you want the C/AL codeunit to perform a single write transaction, it is automatically handled for you. However, if you want the C/AL codeunit to perform multiple write transactions, you must use the COMMIT function to end one write transaction before you can start the next. The COMMIT function separates write transactions in a C/AL code module.

Expand image Example

The following pseudo-code example contains two write transactions. When it begins, a write transaction is automatically started. Using the COMMIT function, you end the first write transaction and prepare for the second. When the code completes, the second write transaction automatically ends.
CopyCode image Copy Code
BeginWriteTransactions
(C/AL Statements) // Transaction 1
COMMIT
(C/AL Statements) // Transaction 2
EndWriteTransactions

Expand image See Also

Concepts

Database


COMPANYNAME Function (Database)

COMPANYNAME Function (Database)
See Also Example
CollapseAll image

Returns the current company name.

Name := COMPANYNAME

Expand image Property Value/Return Value

Type: Text constant or code

The name of the company, or an empty string if no company has been selected.

Expand image Example

This example requires that you create the following variables and text constants.

Variable name | DataType | Length
CompName | Text | 1024
Text Constant | ENU Value
Text000 | The name is %1.
CopyCode image Copy Code
CompName := COMPANYNAME;
MESSAGE(Text000, CompName);

Expand image See Also

Concepts

Database


CURRENTTRANSACTIONTYPE Function (Database)

CURRENTTRANSACTIONTYPE Function (Database)
See Also Example
CollapseAll image

Returns the current transaction type and sets a new type to be assigned.

[TransactionType :=] CURRENTTRANSACTIONTYPE([TransactionType])

Expand image Property Value/Return Value

Type: TransactionType

The type of transaction to be set for the next transaction, or retrieved.

Expand image Remarks

This function sets the transaction type for the next transaction that begins when you are using Microsoft SQL Server. The transaction type determines the extent of locking that is performed on data in SQL Server tables and indexes. It also determines whether modifications to data can occur within the transaction. The following basic transaction types are available:

  • Browse

  • Snapshot

  • UpdateNoLocks

  • Update

  • Report

The Report transaction type maps to one of the other basic transaction types. For more information about the behavior of the transaction types, see TransactionType Property.

Using CURRENTTRANSACTIONTYPE to set a transaction type from within a currently active transaction has no effect on the transaction type. You must set the transaction type before a transaction begins, which occurs at the first database call in a trigger or in a codeunit. If you set the current transaction type to a less isolated transaction behavior, for example, if you try to change an Update transaction to a Browse transaction, the function call is ignored. If you try to change the current transaction type to a more isolated transaction behavior, for example, from Browse to Update, you will receive an error message.

Expand image Example

In Example 1, CURRENTTRANSACTIONTYPE is used to set the required behavior of the next transaction in the database.
CopyCode image Copy Code
//Example 1
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::UpdateNoLocks;

In Example 2, CURRENTTRANSACTIONTYPE is used to return the transaction type setting for the current transaction.
CopyCode image Copy Code
//Example 2
IF CURRENTTRANSACTIONTYPE = TRANSACTIONTYPE::UpdateNoLocks THEN...

Examples 3 and 4 show how to use the CURRENTTRANSACTIONTYPE function to set the transaction type for two separate transactions.

When you set the transaction type as in Example 3, you will get an update (or write) transaction using SERIALIZABLE behavior, which means that modifications are allowed within this transaction. SQL Server will guarantee the serializability of the transaction by placing the appropriate locks when you read from the table in the database.
CopyCode image Copy Code
//Example 3
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Update;

Examples 3 and 4 show how to use the CURRENTTRANSACTIONTYPE function to set the transaction type for two separate transactions.

When you set the transaction type as in Example 4, you will get a read-only, non-locking transaction. This means that no modifications are allowed within this transaction and that SQL Server does not place any locks. It is also possible to read any uncommitted data.
CopyCode image Copy Code
//Example 4
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Browse;

In Example 5, the initial transaction type is UpdateNoLocks. This is usually the default transaction type for a trigger. When you try to change the transaction type from UpdateNoLocks to Browse, which is a less isolated transaction type, the function call is ignored. The current transaction type remains UpdateNoLocks. After the first Table.GET line, again, when you try to change the transaction type from UpdateNoLocks to Browse, the function call is ignored. The current transaction type remains UpdateNoLocks. Next, when you try to change the transaction type from UpdateNoLocks to Update, which is a more isolated transaction type, the function call causes an error message to be generated. The current transaction type remains UpdateNoLocks. After the COMMIT, you can set a new transaction type and change it again if required. After the second Table.GET line, the CURRENTTRANSACTIONTYPE call is ignored. The transaction type remains Update.
CopyCode image Copy Code
//Example 5
OnInsert
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Browse;
Table.GET;
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Browse;
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Update;
COMMIT;
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Browse;
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Update;
Table.GET;
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Browse;
OnInsert.RETURNCOMMIT;

In Example 6, the initial transaction type is UpdateNoLocks. The first two times that you try to change to a less isolated transaction type, the function call is ignored. Finally, when you try to change to a more isolated transaction type, the function call causes an error message to be generated.
CopyCode image Copy Code
//Example 6
CODEUNIT
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Snapshot;
Report 1
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Browse;
Report 2
CURRENTTRANSACTIONTYPE := TRANSACTIONTYPE::Update;

Expand image See Also

Concepts

Database


LOCKTIMEOUT Function (Database)

LOCKTIMEOUT Function (Database)
See Also
CollapseAll image

Determines whether the lock timeout setting is set to on. You can also use this function to override the default setting.

[LockTimeout :=] LOCKTIMEOUT([LockTimeout])

Parameters

LockTimeout

Type: Boolean

The new setting for whether the lock timeout is on.

Expand image Property Value/Return Value

Type: Boolean

This value shows whether to use a lock timeout.

Expand image Remarks

This function has been specifically designed for use in long running processes that should not be terminated because of a lock timeout, for example batch jobs that run overnight.

When the C/AL code is finished running, the default setting is used again. This function does not alter the duration of a lock timeout.

To change the default setting in Microsoft Dynamics NAV, click File, click Database, and then click Alter to open the Alter Database window. Click the Advanced tab and enter or remove the check mark from the Lock timeout field.

Expand image See Also

Concepts

Database


SELECTLATESTVERSION Function (Database)

SELECTLATESTVERSION Function (Database)
See Also
CollapseAll image

Forces the latest version of the database to be used.

SELECTLATESTVERSION

Expand image Remarks

Microsoft Dynamics NAV Database Server

Due to the version principle, you are guaranteed that the database version that you use is consistent, even if you do some time-consuming processing. For example, if you are using a report, and other users update the database while the report is running.

In a situation where this is not desirable and you need to use the latest version of data, you can use SELECTLATESTVERSION to enforce a reloading of the version that the client is using.

SQL Server

This function ensures that the data displayed is the most current data in the database. The function clears all non-locked records from the client cache, thereby ensuring that you read the most recent data.

Expand image See Also

Concepts

Database


SERIALNUMBER Function (Database)

SERIALNUMBER Function (Database)
Example
CollapseAll image

Returns a string which contains the serial number of the license file for your Microsoft Dynamics NAV system.

String := SERIALNUMBER;

Expand image Property Value/Return Value

Type: Text or Code

This string contains the serial number.

Expand image Example

This example requires that you create the following text constants and variables in the C/AL Globals window.

Text constant name | ENU value
Text000 | The serial number for this software package is:\%1
Name | DataType | Length
SN | Text | 30
CopyCode image Copy Code
SN := SERIALNUMBER;
MESSAGE(Text000, SN);

The output of this example is the following:

The serial number for this software package is:

W1-ZA-002-6R75A-7

Note Note

The serial number is dependent on your licensed version of Microsoft Dynamics NAV. The serial number shown here is an example.


SID Function (Database)

SID Function (Database)
See Also Example
CollapseAll image

Retrieves the security identifier (SID) of a Windows user account.

Sid := SID(UserAccount);

Parameters

UserAccount

The Windows user account for which you want to get the SID. You must specify a domain and user name, such as 'cronus\simon'.

Expand image Property Value/Return Value

Type: Text

The SID of the specified Windows user account.

Expand image Remarks

In the Classic client, if you add an alias to the Windows Logins form, then the SID for the alias is automatically added to the form. The SID is the primary key on the Windows Login table. In the RoleTailored client, if you create a page for adding Windows logins, then you must use the SID function to retrieve the SID for the user account so that you can enter the new login into the Windows Login table.

This function only runs on the computer running Microsoft Dynamics NAV Server. If you call this function from the Classic client, then no action occurs.

Expand image Example

This example assigns the SID for Simon's Windows user account to a variable. This example requires that you create the following variables.

Name | DataType | Length
NewSID | Text | 119
UserAccount | Text | 132
CopyCode image Copy Code
UserAccount := 'cronus\simon';
NewSID := SID(UserAccount);

Expand image See Also

Reference

SYNCHRONIZEALLLOGINS Function (Database)
SYNCHRONIZESINGLELOGIN Function (Database)

Concepts

Security Model and Synchronization


SYNCHRONIZEALLLOGINS Function (Database)

SYNCHRONIZEALLLOGINS Function (Database)
See Also
CollapseAll image

Synchronizes the information in the Microsoft Dynamics NAV security system with the Microsoft SQL Server security system.

SYNCHORNIZEALLLOGINS

Expand image Remarks

To run this function, you must have the permissions that are described in the following table.

Location | Role
SQL Server | securityadmin or sysadmin
Database | db_owner or db_securityadmin
Microsoft Dynamics NAV | SUPER

To run this function, the license that is uploaded to the server must contain permissions for the Tools/Security granule. This is the same granule that is required if you synchronize logins from the Classic client.

If you are running with the Standard Security Model, then automatic synchronization occurs when you insert, modify, or delete a Windows login. If you are running with the Enhanced Security Model, then no automatic synchronization occurs, and you must manually synchronize security information.

Running this function has the same effect as clicking Synchronize All Logins in the Classic client. On the Tools menu, point to Security, and then click Synchronize All Logins.

You use this function only from the RoleTailored client or from Web services. If you call this function from the Classic client, then no action occurs.

End-user permissions do not change until the RoleTailored client is restarted.

Before the logins are synchronized, this function verifies that there are no active database transactions in the current session that have not been committed. If there are transactions that have not been committed, then the SYNCHRONIZEALLLOGINS function fails with the following error message:

C/AL function < function name > is not allowed in write transactions. Use the COMMIT function to save the changes before this call, or structure the code differently.

Open transactions that are in a separate session and have not been committed to the database do not affect the success or failure of the SYNCHRONIZEALLLOGINS function. For example, if there are open transactions in a separate client or separate Web service session from the client or session that is executing the SYNCHRONIZEALLLOGINS function, then these transactions do not cause the SYNCHRONIZEALLLOGINS function to fail.

Synchronizing all logons can take considerable time and resources. You should run this function only after you have made all planned changes to user permissions. Additionally, we recommend that you run this function outside of normal business hours.

To synchronize a single login, use the SYNCHRONIZESINGLELOGIN Function (Database).

Expand image See Also

Reference

SYNCHRONIZESINGLELOGIN Function (Database)

Concepts

Security Model and Synchronization


SYNCHRONIZESINGLELOGIN Function (Database)

SYNCHRONIZESINGLELOGIN Function (Database)
See Also Example
CollapseAll image

Synchronizes the information about a single user account in the Microsoft Dynamics NAV security system with the Microsoft SQL Server security system.

SYNCHRONIZESINGLELOGIN(UserAccount);

Parameters

UserAccount

The Windows user account that you want to synchronize. You must specify a domain and user name, such as 'cronus\simon'.

If you use case-sensitive collations in SQL Server, then the case of the user account must match the case of the user account in SQL Server.

Expand image Remarks

To run this function, you must have the permissions that are described in the following table.

Location | Role
SQL Server | securityadmin or sysadmin
Database | db_owner or db_securityadmin
Microsoft Dynamics NAV | SUPER

To run this function, the license that is uploaded to the server must contain permissions for the Tools/Security granule. This is the same granule that is required if you synchronize logins from the Classic client.

If you are running with the Standard Security Model, then automatic synchronization occurs when you insert, modify, or delete a Windows login. If you are running with the Enhanced Security Model, then no automatic synchronization occurs, and you must manually synchronize security information.

You use this function only from the RoleTailored client or from Web services. If you call this function from the Classic client, then no action occurs.

End-user permissions do not change until the RoleTailored client is restarted.

Before the login is synchronized, this function verifies that there are no active database transactions in the current session that have not been committed. If there are transactions that have not been committed, then the SYNCHRONIZESINGLELOGIN function fails with the following error message:

C/AL function < function name > is not allowed in write transactions. Use the COMMIT function to save the changes before this call, or structure the code differently.

Open transactions that are in a separate session and have not been committed to the database do not affect the success or failure of the SYNCHRONIZESINGLELOGIN function. For example, if there are open transactions in a separate client or separate Web service session from the client or session that is executing the SYNCHRONIZESINGLELOGIN function, then these transactions do not cause the SYNCHRONIZESINGLELOGIN function to fail.

To synchronize all logins, use the SYNCHRONIZEALLLOGINS Function (Database).

Expand image Example

This example retrieves the SID for a Windows user account, initializes the ID field based on the SID, inserts the new account into the Windows Login table, and then synchronizes the new account. This example requires that you create the following variables.

Name | DataType | Subtype | Length
UserAccount | Text |  | 132
MyRecord | Record | Windows Login |
CopyCode image Copy Code
UserAccount := 'cronus\simon';
MyRecord.SID := SID(UserAccount);
MyRecord.CALCFIELDS(MyRecord.ID);
MyRecord.INSERT;
SYNCRONIZESINGLELOGIN(MyRecord.ID);

Expand image See Also

Reference

SYNCHRONIZEALLLOGINS Function (Database)
SID Function (Database)

Concepts

Security Model and Synchronization


TRANSACTIONTYPE Data Type

TRANSACTIONTYPE Data Type

Use variables of this complex data type to store the current transaction type. You can then use the value to set the transaction type. You can only change the transaction type when there is no current transaction (immediately after a commit).

For more information about transaction types, see TransactionType Property.

For more information about the rules governing transaction types, see CURRENTTRANSACTIONTYPE Function (Database).


USERID Function (Database)

USERID Function (Database)
See Also Example
CollapseAll image

Returns the ID of the current user.

ID := USERID

Expand image Property Value/Return Value

Type: Text constant or Code

This string contains the ID of the current user.

Expand image Remarks

When you start the application, you are prompted for a user ID and password. This function returns the user ID that you entered.

Expand image Example

This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Length
User | Text | 1024
Text Constant | ENU Value
Text000 | The system was started by %1.
CopyCode image Copy Code
User := USERID;
MESSAGE(Text000, User);

The following is an example of the output of the preceding code:

The system was started by simon.

Expand image See Also

Concepts

Database


Dataport Data Type

Dataport Data Type

Use dataports for importing data from and exporting data to external text files.

Dataports are not supported in the RoleTailored client.

Expand image See Also

Reference

BREAK Function (Dataport, Report, XMLport)
DATAPORT.RUN Function (Dataport)
DATAPORT.RUNMODAL Function (Dataport)
FILENAME Function (Dataport, XMLport)
IMPORT Function (Dataport)
QUIT Function (Dataport, Report, XMLport)
RUN Function (Dataport)
RUNMODAL Function (Dataport)
SETTABLEVIEW Function (Dataport, Form, Report, XMLport)
SKIP Function (Dataport, Report, XMLport)


BREAK Function (Dataport, Report, XMLport)

BREAK Function (Dataport, Report, XMLport)
See Also Example
CollapseAll image

Exits from a loop or a trigger in a data item trigger of a dataport, report, or XMLport.

BREAK

Expand image Remarks

When used inside a loop, such as a WHILE-DO or REPEAT-UNTIL construction, BREAK interrupts the loop. Execution continues with the statement that immediately follows the loop.

When used outside a loop, BREAK causes the current trigger to end.

Compare this with the QUIT Function (Dataport, Report, XMLport).

Expand image Example

This example of code in a report object requires that you create the following variable and text constant in the C/AL Globals window.

Variable name | DataType
MyVar | Integer
Text constant | ENU value
Text000 | The variable is now %1.
CopyCode image Copy Code
REPEAT
  MyVar := MyVar + 1;
  IF MyVar = 5 THEN
    CurrReport.BREAK;
  MESSAGE(Text000,MyVar);
UNTIL Myvar = 10

When you run the preceding code, the loop will end when MyVar is 5.

Expand image See Also

Reference

Dataport Data Type
Report Data Type
XMLport Data Type


DATAPORT.RUN Function (Dataport)

DATAPORT.RUN Function (Dataport)
See Also
CollapseAll image

Loads and executes the dataport that you specify. If, at design time, you do not know the specific dataport you want to run, use this function or the DATAPORT.RUNMODAL Function (Dataport). If you do know the specific dataport you want to run, you can use the RUN Function (Dataport) or the RUNMODAL Function (Dataport).

DATAPORT.RUN(Number [, ReqWindow] [, Record])

Parameters

Number

Type: Integer

The ID of the dataport that you want to execute. You can use the Symbols option on the View menu to choose from a list.

If the dataport you specify does not exist, a run-time error occurs.

ReqWindow

Type: Boolean

Specifies whether to display the request window for the dataport. The request window is part of the dataport object.

If the value is true, the request window is displayed before running the dataport. If the value is false, the dataport is run without displaying the request window.

Record

Type: Record

Specifies which record to use in the dataport. Any filters attached to the record that you specify will be used.

Expand image See Also

Reference

Dataport Data Type


DATAPORT.RUNMODAL Function (Dataport)

DATAPORT.RUNMODAL Function (Dataport)
See Also
CollapseAll image

Loads and executes the dataport that you specify. The dataport is run modally. If, at design time, you do not know the specific dataport that you want to run, use this function or the DATAPORT.RUN Function (Dataport). If you do know the specific dataport that you want to run, you can use the RUN Function (Dataport) or the RUNMODAL Function (Dataport).

DATAPORT.RUNMODAL(Number [, ReqWindow] [, Record])

Parameters

Number

Type: Integer

The ID of the dataport that you want to execute. You can use the Symbols option on the View menu to choose from a list.

If the dataport you specify does not exist, a run-time error occurs.

ReqWindow

Type: Boolean

Specifies whether to display the request window for the dataport. The request window is part of the dataport object.

If the value is true, the request window is displayed before running the dataport. If the value is false, the dataport is run without displaying the request window.

Record

Type: Record

Specifies which record to use in the dataport. Any filters attached to the record that you specify will be used.

Expand image See Also

Reference

Dataport Data Type


FILENAME Function (Dataport, XMLport)

FILENAME Function (Dataport, XMLport)
See Also
CollapseAll image

Returns the current setting of the FileName Property of a dataport or XMLport and sets this property to a new value.

[CurrFileName] := FILENAME([NewFileName])

Parameters

NewFileName

Type: Text

The new setting of the FileName Property.

Expand image Property Value/Return Value

Type: Text

The current setting of the FileName Property.

Expand image See Also

Reference

Dataport Data Type
XMLport Data Type


IMPORT Function (Dataport)

IMPORT Function (Dataport)
See Also
CollapseAll image

Returns the current setting of the Import Property and changes the setting of the property.

[IsImport] := IMPORT([SetImport])

Parameters

SetImport

Type: Boolean

The new setting of the Import Property.

Expand image Property Value/Return Value

Type: Boolean

The current value of the Import Property.

Expand image See Also

Reference

Dataport Data Type


QUIT Function (Dataport, Report, XMLport)

QUIT Function (Dataport, Report, XMLport)
See Also
CollapseAll image

Aborts the processing of a dataport, report, or XMLport.

QUIT

Expand image Remarks

When you use the QUIT function, the dataport, report, or XMLport is exited without committing any changes that were made to the database during the execution. The OnPostReport Trigger, OnPostDataPort Trigger, or OnPostXMLport Trigger trigger will not be called.

Expand image See Also

Reference

Dataport Data Type
Report Data Type
XMLport Data Type


RUN Function (Dataport)

RUN Function (Dataport)
See Also
CollapseAll image

Loads and executes the dataport that you specify.

With dataports, if you know at design time the specific dataport that you want to run, use this function or the RUNMODAL Function (Dataport). If you do not know the specific dataport that you want to run, use the DATAPORT.RUNMODAL Function (Dataport) or DATAPORT.RUN Function (Dataport).

Dataport.RUN

Parameters

Dataport

Type: Dataport

After you define this variable, you can run this function or the RUNMODAL Function (Dataport) on the variable. The variable is automatically cleared after this function runs.

Expand image See Also

Reference

Dataport Data Type


RUNMODAL Function (Dataport)

RUNMODAL Function (Dataport)
See Also
CollapseAll image

Loads and executes the dataport that you specify. If you know at design time the specific dataport that you want to run, use this function or the RUN Function (Dataport). If you do not know the specific dataport that you want to run, use the DATAPORT.RUNMODAL Function (Dataport) or DATAPORT.RUN Function (Dataport).

Dataport.RUNMODAL

Parameters

Dataport

Type: Dataport

After you define this variable, you can run this function or the RUN Function (Dataport) on the variable. The variable is not automatically cleared after this function runs. You must clear the variable after using it.

Expand image Remarks

The request form is run modally.

Expand image See Also

Reference

Dataport Data Type


SETTABLEVIEW Function (Dataport, Form, Report, XMLport)

SETTABLEVIEW Function (Dataport, Form, Report, XMLport)
See Also
CollapseAll image

Applies the table view on the current record as the table view for the form, report, dataport, or XMLport.

SETTABLEVIEW(Record)

Parameters

Record

Type: Record

The record whose table view you want to apply to the form or data item.

Expand image Remarks

The table view is the view of the table that you present to the user. You determine what records the user can see by setting filters, determining the sorting order, and selecting the keys.

This function only narrows the view of the table that was set through the SourceTableView Property of the form, or through the DataItemTableView Property of the data item.

If you use this function and the SaveTableView Property of the form is set to "Yes", the current table view in the setup file will not be saved.

Expand image See Also

Reference

Dataport Data Type
Form Data Type
Report Data Type
XMLport Data Type


SKIP Function (Dataport, Report, XMLport)

SKIP Function (Dataport, Report, XMLport)
See Also Example
CollapseAll image

Skips the current iteration of the current dataport, report, or XMLport.

SKIP

Expand image Remarks

While you can use SHOWOUTPUT Function (Report) to suppress printing the output from a section in a report, SKIP allows you to suppress any processing and move on.

Expand image Example

If you perform some processing in the OnAfterGetRecord trigger of a data item and you do not want this processing to take place in some situations, you can use SKIP as in the following code example.
CopyCode image Copy Code
IF Balance = 0 THEN
  CurrReport.SKIP
ELSE
  ... // some processing

A typical situation in which you will use SKIP is when you want to retrieve records from a related table by using values in the current record for forming a filter. If the values in the current record already indicate that no records from the related table will be retrieved, there is no need to perform this processing and you can use SKIP to avoid it.

Expand image See Also

Reference

OnAfterGetRecord (Data Items) Trigger
OnAfterGetRecord Trigger
OnAfterGetRecord (XMLports) Trigger
Dataport Data Type
Report Data Type
XMLport Data Type


DateFormula Data Type

DateFormula Data Type

Use this data type to contain a date formula that has the same capabilities as an ordinary input string for the CALCDATE Function (Date). The DateFormula data type is used to provide multilanguage capabilities to the CALCDATE Function (Date).

Expand image Remarks

When a date calculation formula is stored in a DateFormula field, it is converted to a generic, non-language dependent format. When a date calculation formula is retrieved from a DateFormula field, it is converted to a valid date conversion string for the currently selected language.

To assign a value to a DateFormula data type, whether it is a field or a variable, you must use the EVALUATE Function.

Example

This example requires that you create a DateFormulaVariable variable that is a DateFormula data type.

CopyCode image Copy Code
IF FORMAT(DateFormulaVariable) = ' ' THEN
  EVALUATE(DateFormulaVariable, '1W');

You must use the FORMAT Function (Code, Text) to make a comparison with a text string. If you do not use this function, then the IF statement will fail because you cannot compare a DateFormula data type with a Text data type.

Expand image See Also

Concepts

Developing Multilanguage-Enabled Applications


Dates and Times

Dates and Times

This section contains the following topics:

  • Date Data Type

  • DateTime Data Type

  • Duration Data Type

  • Time Data Type

  • Date and Time Functions

  • DateTime Functions


Date Data Type

Date Data Type

Denotes a date ranging from January 3, 0001 to December 31, 9999. An undefined or blank date is specified by 0D. The undefined date is considered to be before all other dates.

The displayed text format of the date is determined by your Regional and Language Options in Windows.

Expand image Remarks

All dates have a corresponding closing date. The closing date for a given date is defined as a period of time that follows a given date and precedes the next normal date. Closing dates are sorted after their corresponding given date and before the next normal date.

The format of a normal date is <MMDDYY>D

The format of a closing date is <MMDDYY>C

If you use a date that is outside the valid date range, a run-time error occurs.

The following examples are valid assignments of dates with a Date variable MyDate on a computer with the regional format set to English (United States).

CopyCode image Copy Code
MyDate := 0D;
MyDate := 112708D;
MESSAGE(FORMAT(MyDate));
MyDate := 11271808D;
MESSAGE(FORMAT(MyDate));
MyDate := 033108D;
MESSAGE(FORMAT(MyDate));

The following shows what the message windows display on a computer with the regional format set to English (United States).

11/27/08

11/27/1808

03/31/08

Note Note

When you assign a value to a date variable, the value that you assign must be in the correct format for the regional setting of the computer. For example, if the computer is set to English (United States), then MyDate := 271108D; results in a compiler error.

Expand image SQL Server Option

Microsoft SQL Server stores information about both date and time in columns of the DATETIME types. For date fields, Microsoft Dynamics NAV uses only the date and uses a constant value for the time. For a normal date, this constant value contains 00:00:00:000. For a closing date, it contains 23:59:59:000.

The Microsoft Dynamics NAV undefined date is represented by the earliest valid date in SQL Server. The earliest valid date in SQL Server for a DATETIME is 01-01-1753 00:00:00:000.

If you use a SQL Server database with Microsoft Dynamics NAV 2009, and if you store a date in the database that is outside the valid range for a SQL DATETIME, a run-time error occurs.

Expand image Changes from Previous Versions of Microsoft Dynamics NAV

In previous versions of Microsoft Dynamics NAV, the date data type denotes dates ranging from January 1, 0000 to December 31, 9999, and includes the undefined date, 0D. The undefined date was stored as January 1, 0000. Microsoft Dynamics NAV 2009 supports the date January 1, 0000 as a special case for compatibility with previous versions.

Expand image See Also

Reference

CALCDATE Function (Date)
CLOSINGDATE Function (Date)
DATE2DMY Function (Date)
DATE2DWY Function (Date)
DATI2VARIANT Function (Date, Variant)
DMY2DATE Function (Date)
DWY2DATE Function (Date)
NORMALDATE Function (Date)
TODAY Function (Date)
VARIANT2DATE Function (Date, Variant)
WORKDATE Function (Date)


DateTime Data Type

DateTime Data Type

Denotes a date and time ranging from January 3, 0001, 00:00:00.000 to December 31, 9999, 23:59:59.999. An undefined or blank DateTime is specified by 0DT.

The displayed text format of a DateTime is determined by your Regional and Language Options in Windows.

Expand image Remarks

A DateTime is stored in the database as Coordinated Universal Time (UTC). UTC is the international time standard (formerly Greenwich Mean Time, or GMT). Zero hours UTC is midnight at 0 degrees longitude.

The DateTime is always displayed as local time in Microsoft Dynamics NAV. Local time is determined by the time zone regional settings used by your computer. You must always enter DateTimes as local time. When you enter a DateTime as local time, it is converted to UTC using the current settings for the time zone and daylight savings time.

The DateTime data type does not support closing dates.

By default, DateTimes are displayed using the standard display format. When you use the standard display format, seconds and milliseconds are not displayed until you select the DateTime field. Furthermore, if you export your data using dataport export or by writing it to a file, the seconds and milliseconds are not exported unless you specify that DateTime fields use another format and display this information. For more information about how DateTimes are displayed and the formats that are available, see Format Property.

The only constant available when you use the DateTime data type is the undefined DateTime, 0DT. To assign a constant value to a DateTime variable you must use the CREATEDATETIME Function (DateTime).

If you use a date that is outside the valid date range, a run-time error occurs.

SQL Server

In Microsoft SQL Server, the earliest permitted DateTime is January 1, 1753, 00:00:00.000. The latest permitted DateTime is December 31, 9999, 23:59:59.999.

If you use a SQL Server database with Microsoft Dynamics NAV 2009, and if you store a date in the database that is outside the valid range for a SQL DATETIME, a run-time error run-time occurs.

Expand image Changes from Previous Versions of Microsoft Dynamics NAV

In previous versions of Microsoft Dynamics NAV, the DateTime data type denotes DateTimes ranging from January 1, 0000, 00:00:00.000 to December 31, 9999, 23:59:59.999, and includes the undefined DateTime, 0DT. Microsoft Dynamics NAV 2009 supports DateTimes with date January 1, 0000 as a special case for compatibility with previous versions.

Expand image See Also

Reference

CREATEDATETIME Function (DateTime)
CURRENTDATETIME Function (DateTime)
DT2DATE Function (DateTime)
DT2TIME Function (DateTime)
ROUNDDATETIME Function (DateTime)


Duration Data Type

Duration Data Type
See Also Example
CollapseAll image

Represents the difference between two DateTimes. This value can be negative. It is stored as a 64-bit integer. The integer value is the number of milliseconds during the duration.

The following are examples of durations:

DATETIME-DATETIME=DURATION

DATETIME-DURATION=DATETIME

DATETIME+DURATION=DATETIME

Expand image Example

This example shows how to calculate the difference between two DateTimes. It requires that you define the following variables.

Variable | Data type
DateTime1 | DateTime
Datetime2 | DateTime
Duration | Duration

This example is run on a computer with the Current Format in the Regional and Language Options set to English (United States).

CopyCode image Copy Code
DateTime1 := CREATEDATETIME(010109D, 080000T); // January 1, 2009 at 08:00:00 AM
DateTime2 := CREATEDATETIME(050509D, 133001T); // May 5, 2009 at 1:30:01 PM
Duration := DateTime2 - DateTime1;
MESSAGE(FORMAT(Duration));

The message window displays the following:

124 days 4 hours 30 minutes 1 second

Expand image See Also

Reference

DateTime Data Type


Time Data Type

Time Data Type

Denotes a time ranging from 00:00:00.000 to 23:59:59.999. An undefined or blank time is specified by 0T.

The displayed text format of the time is determined by your Regional and Language Options in Windows.

The following are examples of valid assignments of times to a Time variable MyTime.

CopyCode image Copy Code
MyTime := 0T;
MyTime := 1159T;
MESSAGE(FORMAT(MyTime));
MyTime := 115934T;
MESSAGE(FORMAT(MyTime));
MyTime := 115934.444T;
MESSAGE(FORMAT(MyTime));
MyTime := 0300T;
MESSAGE(FORMAT(MyTime));

The following shows what the message windows display on a computer with the regional format set to English (United States).

11:59:00 AM

11:59:34 AM

11:59:34.444 AM

3:00:00 AM

Expand image SQL Server Option

Microsoft SQL Server stores information about both date and time in columns of the DATETIME type. Microsoft Dynamics NAV uses only the time part and inserts a constant value for the date: 01-01-1754.

The Microsoft Dynamics NAV undefined time is represented by the same value as an undefined date. The undefined date is represented by the earliest valid DATETIME in SQL Server, which is 01-01-1753 00:00:00:000.

Expand image See Also

Reference

TIME Function (Time)
VARIANT2TIME Function (Date, Variant)
CREATEDATETIME Function (DateTime)
DT2TIME Function (DateTime)


Date and Time Functions

Date and Time Functions

This section contains the following topics:

  • CALCDATE Function (Date)

  • CLOSINGDATE Function (Date)

  • DATE2DMY Function (Date)

  • DATE2DWY Function (Date)

  • DATI2VARIANT Function (Date, Variant)

  • DMY2DATE Function (Date)

  • DWY2DATE Function (Date)

  • NORMALDATE Function (Date)

  • TIME Function (Time)

  • TODAY Function (Date)

  • VARIANT2DATE Function (Date, Variant)

  • VARIANT2TIME Function (Date, Variant)

  • WORKDATE Function (Date)


CALCDATE Function (Date)

CALCDATE Function (Date)
See Also
CollapseAll image

Calculates a new date that is based on a date expression and a reference date.

NewDate := CALCDATE(DateExpression [, Date])

Parameters

DateExpression

Type: Text, Code, or DateFormula

The date expression can be any length. The string is interpreted from left to right with one subexpression at a time. The following rules describe the valid syntax of date expressions:

  • DateExpression = [<SubExpression>][<SubExpression>][<SubExpression>]

  • <SubExpression> = [<Sign>] <Term>

  • <Sign> = + | -

  • <Term> = <Number><Unit> | <Unit><Number> | <Prefix><Unit>

  • <Number> = Positive integer

  • <Unit> = D | WD | W | M | Q | Y (D=day, WD=weekday, W=week, M=month, Q=quarter, Y=year)

  • <Prefix> = C (C=current)

These production rules show that date expressions consist of zero, one, two, or three subexpressions. Each subexpression comprises an optional sign and a term. The following are some typical examples of terms:

  • 30D (30 days; corresponds to <Number><Unit>)

  • WD2 (weekday number 2; corresponds to <Unit><Number>)

  • CW (current week; corresponds to <Prefix><Unit>)

The internal calendar of C/SIDE starts on Monday and ends on Sunday. This means that Monday is weekday 1 and Sunday is weekday 7.

A run-time error occurs if the syntax of DateExpression is incorrect.

Date

Type: Date

Use this optional parameter to define a reference date. The default is the current system date.

If you omit this optional value the current system date is used.

Expand image Property Value/Return Value

Type: Date

The date that is computed from the reference date and the date expression.

Expand image Remarks

DateExpression can be a field or variable of type Text or Code, and it can be a field or variable of type DATEFORMULA. The benefit of using a DateFormula field or variable is that the date formula becomes language independent.

The user can enter formulas in the currently selected language. The formula is stored in a generic format in a field or variable. When the formula needs to be displayed, the actual string that is displayed is converted to the currently selected language.

For example, if a user with language set to ENG (English) enters the date formula "1W+1D" for one week and one day, then a user with the language set to FRA (French) sees "1S+1J," and a user with the language set to ESP (Spanish) sees "1S+1D".

If a date formula is entered with < > delimiters surrounding it, then the date formula is stored in a generic, nonlanguage-dependent format. This makes it possible to develop date formulas that are not dependent on the currently selected language.

For more information about calculating the duration between two DateTimes, see Duration Data Type.

Expand image Example 1

This code example shows how to use the production rules that were previously described.

CopyCode image Copy Code
<CQ+1M-10D>

This should be interpreted as the following: current quarter + 1 month - 10 days.

The DateExpression is composed of the following:

<Prefix><Unit><Sign><Number><Unit><Sign><Number><Unit>

Note Note

The angle brackets (< >) specify that the expression is not translated, regardless of the application language. For more information about multilanguage capabilities with date formulas, see Developing Multilanguage-Enabled Applications.

Expand image Example 2

This example shows how to use the CALCDATE function.

This code example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text000 | 'The reference date is: %1 \'
Text001 | 'The expression: %2 returns %3\'
Text002 | 'The expression: %4 returns %5\'
Text003 | 'The expression: %6 returns %7'
CopyCode image Copy Code
Expr1 := '<CQ+1M-10D>'; // Current quarter + 1 month - 10 days
Expr2 := '<-WD2>'; // The last weekday no.2, (last Tuesday)
Expr3 := '<CM+30D>'; // Current month + 30 days
RefDate := 052196D;
Date1 := CALCDATE(Expr1, RefDate);
Date2 := CALCDATE(Expr2, RefDate);
Date3 := CALCDATE(Expr3, RefDate);
MESSAGE(Text000 + Text001 + Text002 + Text003,
  RefDate, Expr1, Date1, Expr2, Date2, Expr3, Date3);

The message window displays the following text:

The reference date is: 05/21/96

The expression: CQ+1M-10D returns 07/20/96

The expression: -WD2 returns 05/14/96

The expression: CM+30D returns 06/30/96

Expand image See Also

Concepts

Date and Time Functions
Developing Multilanguage-Enabled Applications


CLOSINGDATE Function (Date)

CLOSINGDATE Function (Date)
See Also
CollapseAll image

Returns the closing date for a Date Data Type.

ClosingDate := CLOSINGDATE(Date)

Parameters

Date

Type: Date

The input date.

Expand image Property Value/Return Value

Type: Date

The corresponding closing date for the input date.

Expand image Remarks

All dates have a corresponding closing date. A closing date is a period in time following the given date but before the next normal date. Closing dates are sorted immediately after the corresponding normal date but before the next normal date.

xxxxxxD: Normal date

xxxxxxC: Closing date

The compiler cannot convert the expression xxxxxxC to a Date data type. Therefore, you must use the CLOSINGDATE function to create a closing date.

Expand image Example 1

The first example shows how to use the CLOSINGDATE function. A normal date is given as input. This code example requires that you create the following variables and text constants in the C/AL Globals window.

Name | DataType
Date1 | Date
CloDate | Date
Text Constant | ENU Value
Text000 | The closing date for %1 is %2.
CopyCode image Copy Code
Date1 := 040409D;
CloDate := CLOSINGDATE(Date1);
MESSAGE(Text000, Date1, CloDate);

The following message is displayed:

The closing date for 04/04/09 is C04/04/09.

Expand image Example 2

The second example shows some statements that do not work and explains why they do not work. This example requires that you create the following variables and text constants in the C/AL Globals window.

Name | DataType
Date1 | Date
CloDate1 | Date
CloDate2 | Date
Text Constant | ENU Value
Text001 | The closing date for %1 is %2.
CopyCode image Copy Code
// Date1 := 040409C;
// The previous statement does not compile because the compiler
// cannot convert '040409C' to a Date data type.
Date1 := 040409D;
// The previous statement compiles.
// The compiler converts '040409D' to a Date data type.
// CloDate1 := CLOSINGDATE(050509C);
// The previous statement does not compile because the compiler
// cannot convert '050509C' to a Date data type and the CLOSINGDATE
// function requires a Date data type for its parameter.
CloDate1 := CLOSINGDATE(Date1);
// The previous statement compiles.
// Date1 is a Date data type.
CloDate2 := CLOSINGDATE(CloDate1);
// The previous statement compiles.
// CloDate1 is a Date data type.
MESSAGE(Text001, CloDate1, CloDate2);

The following message is displayed:

The closing date for C04/04/09 is C04/04/09.

Expand image See Also

Concepts

Date and Time Functions


DATE2DMY Function (Date)

DATE2DMY Function (Date)
See Also Example
CollapseAll image

Returns the day, month, or year of a Date Data Type.

Number := DATE2DMY(Date, What)

Parameters

Date

Type: Date

The input date.

What

Type: Integer

Specifies what the function should return. The valid options are 1, 2, and 3.

The value 1 corresponds to Day (1-31).

The value 2 corresponds to Month (1-12).

The value 3 corresponds to Year.

Expand image Property Value/Return Value

Type: Integer

The day, month, or year of the Date parameter.

Expand image Example

This example shows how to use the DATE2DMY function. This code example requires you to create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
InputDate | Date
Day | Integer
Month | Integer
Year | Integer
Text constant name | Constant Value
Text000 | Today is day %1 of month %2 of the year %3.
CopyCode image Copy Code
InputDate := TODAY;
Day := DATE2DMY(InputDate,1);
Month := DATE2DMY(InputDate,2);
Year := DATE2DMY(InputDate,3);
MESSAGE(Text000,Day,Month,Year);

The message window displays the following:

Today is day 16 of month 2 of the year 2008.

Expand image See Also

Concepts

Date and Time Functions


DATE2DWY Function (Date)

DATE2DWY Function (Date)
See Also Example
CollapseAll image

Returns the day of the week, week number, or year of a Date Data Type.

Number := DATE2DWY(Date, What)

Parameters

Date

Type: Date

The input date.

What

Type: Integer

Specifies what the function returns. The valid options are 1, 2, and 3.

The value 1 corresponds to day of the week (1-7, Monday = 1).

The value 2 corresponds to week number (1-53).

The value 3 corresponds to year.

Expand image Property Value/Return Value

Type: Integer

The resulting day of the week, week number, or year.

Expand image Remarks

If the input date to the DATE2DWY function is in a week which spans two years, the DATE2DWY function computes the output year as the year that has more days of the given week. For example, if the input date is 010109, then the date is in a week that starts on Monday, December 29, 2008, and ends Sunday, January 4, 2009. This week has three days in 2008 and four days in 2009, so the output year is 2009.

Expand image Example

This example shows a special case that occurs when you use the DATE2DWY function in a week which spans two years. This code example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
InputDate | Date
DayOfWeek | Integer
WeekNumber | Integer
Year | Integer
Text constant name | ENU value
Text000 | The date %1 corresponds to:\
Text001 | The day of the week: %2\
Text002 | The week number: %3\
Text003 | The year: %4
CopyCode image Copy Code
InputDate := 010109D;
DayOfWeek := DATE2DWY(InputDate, 1);
WeekNumber := DATE2DWY(InputDate, 2);
Year := DATE2DWY(InputDate, 3);
MESSAGE(Text000 + Text001 + Text002 + Text003, InputDate, DayOfWeek, WeekNumber, Year);

The message window displays the following:

The date 01/01/09 corresponds to:

The day of the week: 4

The week number: 1

The year: 2009

This example shows that the date 01/01/09 is regarded as day number 4 (Thursday) in week number 1 in the year 2009.

Expand image See Also

Concepts

Date and Time Functions


DATI2VARIANT Function (Date, Variant)

DATI2VARIANT Function (Date, Variant)
See Also
CollapseAll image

Creates a variant that contains a VT_DATE.

Variant := DATI2VARIANT(Date, Time)

Parameters

Date

Type: Date

The input date.

Time

Type: Time

The input time.

Expand image Property Value/Return Value

Type: Variant

Expand image See Also

Reference

Variant Data Type

Concepts

Date and Time Functions


DMY2DATE Function (Date)

DMY2DATE Function (Date)
See Also Example
CollapseAll image

Returns a Date Data Type based on a day, month, and year.

Date := DMY2DATE(Day [, Month] [, Year])

Parameters

Day

Type: integer

The number of the day in the month (1-31)

Month

Type: integer

The number of the month in the year (1-12). If you omit this optional parameter, the current month will be used as the default.

Year

Type: integer

The four-digit number of the year. If you omit this optional parameter, the current year is used as the default.

Expand image Property Value/Return Value

Type: date

The resulting date.

Expand image Example

This code example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
Day | Integer
Month | Integer
Year | Integer
OutputDate | Date
Text constant name | ENU Value
Text000 | Day number %1, month number %2, and year number %3 corresponds to the date %4.
CopyCode image Copy Code
Day := 17;
Month := 2;
Year := 2009;
OutputDate := DMY2DATE(Day, Month, Year);
MESSAGE(Text000, Day, Month, Year, OutputDate);

On a computer with the regional format set to English (United States), the message window displays the following:

Day number 17, month number 2, and year number 2009 corresponds to the date 02/17/09.

Expand image See Also

Concepts

Date and Time Functions


DWY2DATE Function (Date)

DWY2DATE Function (Date)
See Also Example
CollapseAll image

Returns a Date data type that is based on a week day, a week, and a year.

Date := DWY2DATE(WeekDay [, Week] [, Year]))

Parameters

Weekday

Type: Integer

The number of the day in the week (1-7). Monday is day number 1.

Week

Type: Integer

The number of the week. Week 1 is the first week of the year that has four or more days in the year. If you omit this optional parameter, the current week is used as the default.

Year

Type: Integer

The four-digit number of the year. If you omit this optional parameter, the year of the current week is used as the default.

Expand image Property Value/Return Value

Type: Date

The resulting date.

Expand image Remarks

A special situation occurs if the week (Week) that is input into DWY2DATE spans two years. Depending on Weekday, the year of the output Date can differ from the input year. This scenario is shown in the following code example.

Expand image Example

The input week in this example spans two years. This code example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
DayOfWeek | Integer
Week | Integer
Year | Integer
OutputDate | Date
Text constant name | ENU value
Text000 | Day %1 of week %2 in the year %3 is the date %4.
CopyCode image Copy Code
DayOfWeek := 1;
Week := 1;
Year := 2009;
OutputDate := DWY2DATE(DayOfWeek, Week, Year);
MESSAGE(Text000, DayOfWeek, Week, Year, OutputDate);

On a computer with the regional format set to English (United States), the message window displays the following:

Day 1 of week 1 in the year 2009 is the date: 12/29/08.

The example shows that the 1st day of the week in the 1st week of the year 2009 is regarded as the date December 29, 2008. The first week of the year 2009 is the first week that has four or more days in the year 2009. That week begins on Monday, December 28, 2008, and ends on Sunday, January 4, 2009.

The input week in this example spans two years. This code example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | Data type
DayOfWeek | Integer
Week | Integer
Year | Integer
OutputDate | Date
Text constant | ENU value
Text000 | Day %1 of week %2 in the year %3 is the date %4.
CopyCode image Copy Code
DayOfWeek := 1;
Week := 1;
Year := 2010;
OutputDate := DWY2DATE(DayOfWeek, Week, Year);
MESSAGE(Text000, DayOfWeek, Week, Year, OutputDate);

On a computer with the regional format set to English (United States), the message window displays the following:

Day 1 of week 1 in the year 2010 is the date: 01/04/10.

The example shows that the 1st day of the week in the 1st week of the year 2010 is regarded as the date January 4, 2010. The first week of the year 2010 is the first week that has four or more days in the year 2010. That week begins on Monday, January 4, 2010, and ends on Sunday, January 10, 2010.

This example shows how to use the DWY2DATE function without specifying the optional Year parameter. The output in this example depends on the day on which you run the code. This code example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
DayOfWeek | Integer
Week | Integer
OutputDate | Date
Text constant | ENU value
Text000 | Day %1 of week %2 is the date %3.
CopyCode image Copy Code
DayOfWeek := 1;
Week := 1;
OutputDate := DWY2DATE(DayOfWeek, Week);
MESSAGE(Text000, DayOfWeek, Week, OutputDate);

On a computer with the regional format set to English (United States), if you ran the code on January 1, 2009, then the message window displays the following:

Day 1 of week 1 is the date: 12/29/08.

If you do not specify the year, then the year of the current week is used. On January 1, 2009, the current week is the week that begins on December 29, 2008 and ends on January 4, 2009. This week has four days in 2009 so the year of the current week is 2009. The 1st day of the first week of 2009 is 12/29/08.

On a computer with the regional format set to English (United States), if you ran the code on January 1, 2010, then the message window displays the following:

Day 1 of week 1 is the date: 12/29/08.

On January 1, 2010, the current week is the week that begins on December 28, 2009 and ends on January 3, 2009. This week has four days in 2009 so the year of the current week is 2009. The 1st day of the first week of 2009 is 12/29/08.

Expand image See Also

Concepts

Date and Time Functions


NORMALDATE Function (Date)

NORMALDATE Function (Date)
See Also
CollapseAll image

Returns the normal date (as opposed to the closing date) for the argument Date.

NormalDate := NORMALDATE(Date)

Parameters

Date

Type: Date

The input date. You can enter a closing date or a normal date. A run-time error occurs if the value of Date is set to the undefined date (0D).

Expand image Property Value/Return Value

Type: Date

The resulting normal date. If the input date is either a normal date or a closing date, then the return value is a normal date.

Expand image Remarks

All dates have a corresponding closing date. A closing date is a period of time that follows the given date but comes before the next normal date. Closing dates are sorted immediately after the corresponding normal date and before the next normal date.

xxxxxxD: normal date

xxxxxxC: closing date

Expand image Example 1

The input date is a normal date. This code example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
InputDate | Date
OutputDate | Date
Text constant name | ENU value
Text000 | The normal date for %1 is %2.
CopyCode image Copy Code
InputDate := 040409D;
OutputDate := NORMALDATE(InputDate);
MESSAGE(Text000, InputDate, OutputDate);

On a computer with the regional format set to English (United States), the message window displays the following:

The normal date for 04/04/09 is 04/04/09.

Expand image Example 2

The input date is a closing date. This code example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
InputDate | Date
OutputDate | Date
Text constant name | ENU value
Text001 | The normal date for %1 is %2.
CopyCode image Copy Code
InputDate := CLOSINGDATE(040409D);
OutputDate := NORMALDATE(InputDate);
MESSAGE(Text001, InputDate, OutputDate);

On a computer with the regional format set to English (United States), the message window displays the following:

The normal date for C04/04/09 is 04/04/09.

Expand image See Also

Concepts

Date and Time Functions


TIME Function (Time)

TIME Function (Time)
See Also Example
CollapseAll image

Retrieves the current time from the operating system.

Time := TIME

Expand image Property Value/Return Value

Type: Time

The current time.

Expand image Remarks

You can only use the TIME function to retrieve the time from the operating system. You cannot use it to set the time in the operating system.

Expand image Example

This example requires that you create the following text constant in the C/AL Globals window.

Text constant name | ENU Value
Text000 | The current system time is %1.
CopyCode image Copy Code
MESSAGE(Text000, TIME);

On a computer with the regional format set to English (United States), the message window could display the following:

The current system time is 11:15:46 AM.

Expand image See Also

Reference

Time Data Type

Concepts

Date and Time Functions


TODAY Function (Date)

TODAY Function (Date)
See Also Example
CollapseAll image

Returns the current date set in the operating system.

Date := TODAY

Expand image Property Value/Return Value

Type: date

The current date defined by the operating system.

Expand image Remarks

You can only use the TODAY function to retrieve the current date from the operating system. You cannot use it to set the date in the operating system.

Expand image Example

This example shows how to use the TODAY function. This example requires that you create the following text constant in the C/AL Globals window.

Text Constant | ENU Value
Text000 | 'The current date is: %1'
CopyCode image Copy Code
MESSAGE(Text000, TODAY);

The message window could display the following:

The current date is: 05/27/08

Expand image See Also

Concepts

Date and Time Functions


VARIANT2DATE Function (Date, Variant)

VARIANT2DATE Function (Date, Variant)
See Also
CollapseAll image

Returns a date from a VT_DATE variant.

Date := VARIANT2DATE(Variant)

Parameters

Variant

Type: Variant

The input variant.

Expand image Property Value/Return Value

Type: Date

The resulting date.

Expand image See Also

Reference

Variant Data Type

Concepts

Date and Time Functions


VARIANT2TIME Function (Date, Variant)

VARIANT2TIME Function (Date, Variant)
See Also
CollapseAll image

Returns a time from a VT_DATE variant.

Time := VARIANT2TIME(Variant)

Parameters

Variant

Type: Variant

The input variant.

Expand image Property Value/Return Value

Type: Time

The resulting time.

Expand image See Also

Reference

Variant Data Type

Concepts

Date and Time Functions


WORKDATE Function (Date)

WORKDATE Function (Date)
See Also Example
CollapseAll image

Sets and returns the work date for the current session.

[WorkDate]:= WORKDATE([NewDate])

Parameters

NewDate

Type: date

The new work date you want to set. If you omit this value the function returns the current work date.

Expand image Property Value/Return Value

Type: date

The current work date.

Expand image Remarks

This function returns the work date chosen using the Work Date option on the Tools menu. If the user did not choose a work date, the the current system date is returned.

Expand image Example

This example shows how to use the WORKDATE function. This example requires that you create the following text constant in the C/AL Globals window.

Text Constant | ENU Value
Text000 | 'The work date is: %1'
CopyCode image Copy Code
MESSAGE(Text000, WORKDATE);

The message window could display the following:

The work date is: 05/27/06

Expand image See Also

Concepts

Date and Time Functions


DateTime Functions

DateTime Functions

This section contains the following topics:

  • CREATEDATETIME Function (DateTime)

  • CURRENTDATETIME Function (DateTime)

  • DT2DATE Function (DateTime)

  • DT2TIME Function (DateTime)

  • ROUNDDATETIME Function (DateTime)


CREATEDATETIME Function (DateTime)

CREATEDATETIME Function (DateTime)
See Also
CollapseAll image

Creates a datetime from a date and a time.

DateTime := CREATEDATETIME(Date, Time)

Parameters

Date

Type: date

The date that you want to use to create a datetime.

You cannot use an undefined date to create a datetime.

Time

Type: time

The time that you want to use to create a datetime.

You cannot use an undefined time to create a datetime.

Expand image Property Value/Return Value

Type: datetime

The concatenated datetime.

Expand image See Also

Concepts

DateTime Functions


CURRENTDATETIME Function (DateTime)

CURRENTDATETIME Function (DateTime)
See Also
CollapseAll image

Returns the current datetime.

DateTime := CURRENTDATETIME

Expand image Property Value/Return Value

Type: datetime

The current datetime.

Expand image See Also

Concepts

DateTime Functions


DT2DATE Function (DateTime)

DT2DATE Function (DateTime)
See Also
CollapseAll image

Returns the date part of a datetime.

Date := DT2DATE(Datetime)

Parameters

Datetime

Type: datetime

The datetime of which you want to return the date part.

Expand image Property Value/Return Value

Type: date

The date part of the datetime.

Expand image Remarks

If datetime is undefined, this function returns an undefined date.

Expand image See Also

Concepts

DateTime Functions


DT2TIME Function (DateTime)

DT2TIME Function (DateTime)
See Also
CollapseAll image

Returns the time part of a datetime.

Time := DT2TIME(Datetime)

Parameters

Datetime

Type: datetime

The datetime of which you want to return the time part.

Expand image Property Value/Return Value

Type: time

The time part of the datetime.

Expand image Remarks

If datetime is undefined, this function returns an undefined time.

Expand image See Also

Concepts

DateTime Functions


ROUNDDATETIME Function (DateTime)

ROUNDDATETIME Function (DateTime)
See Also Example
CollapseAll image

Rounds a DateTime.

NewDateTime := ROUNDDATETIME(Datetime [, Precision][, Direction])

Parameters

Datetime

Type: DateTime

The DateTime that you want to round.

Precision

Type: BigInteger

This optional parameter determines the precision used when rounding. The default value is 1000, which rounds to the nearest second.

You can only use positive BigIntegers.

Direction

Type: Text or Code

This optional parameter specifies how to round the DateTime. The default rounding method is '='. You can change the method by using the following options:

  • '=' rounds up or down to the nearest value (default). Values of 5 or greater are rounded up. Values less than 5 are rounded down.

  • '>' rounds up

  • '<' rounds down

Expand image Property Value/Return Value

Type: DateTime

The rounded result.

Expand image Remarks

A variable of type DateTime is stored as a 64 bit integer. The integer value is the number of milliseconds since year 0. When you call ROUNDDATETIME, the DateTime integer value is rounded as a numeric variable.

If you use 1 for the Precision parameter, then the resulting DateTime is rounded to the nearest millisecond. If you use 1000 for the Precision parameter, which is the default value, then the resulting DateTime will be rounded to the nearest second.

We recommend that you do not use a value greater than 60*60*1000, which is the number of milliseconds in an hour, for the Precision parameter. The Regional and Language Options in Windows affect how the hour and date parts of a DateTime are rounded. To display a DateTime in a specific format, we recommend that you use the FORMAT Function (Code, Text) instead of the ROUNDDATETIME function.

Expand image Example

This example shows how to use the ROUNDDATETIME function to round to the nearest second. This example requires that you create the following text constant in the C/AL Globals window.

Text constant name | ENU value
Text000 | ROUNDDATETIME(%1, %2) returns %3.
CopyCode image Copy Code
DateToRound := 112708D;
TimeToRound := 093524.567T;
DateTimeToRound := CREATEDATETIME(DateToRound, TimeToRound);
Precision := 1000L;
FormatString := '<Month,2>/<Day,2>/<Year> <Hours24,2>:<Minutes,2>:<Seconds,2>.<Thousands,3>';
Result := ROUNDDATETIME(DateTimeToRound, Precision);
MESSAGE(TEXT000, Format(DateTimeToRound,0,FormatString), Precision, Format(Result,0,FormatString));

The message window displays the following:

ROUNDDATETIME(11/27/08 09:35:24.567, 1000) returns 11/27/08 09:35:25.000.

Expand image See Also

Reference

FORMAT Function (Code, Text)
Format Property

Concepts

DateTime Functions


Dialog Data Type

Dialog Data Type

Variables of this complex data type store dialog windows. These variables also give you access to a number of dialog functions, such as OPEN Function (Dialog), CLOSE Function (Dialog), and so on.

Expand image Dialog Functions

BEEP Function (Dialog)

CLOSE Function (Dialog)

CONFIRM Function (Dialog)

ERROR Function (Dialog)

INPUT Function (Dialog)

MESSAGE Function (Dialog)

OPEN Function (Dialog)

STRMENU Function (Dialog)

UPDATE Function (Dialog)

YIELD Function (Dialog)


BEEP Function (Dialog)

BEEP Function (Dialog)
See Also
CollapseAll image

Sounds a tone through the computer's speaker. For example, you can use the function to signal that the wrong kind of data has been entered in a control or that your application is waiting for input from the user.

BEEP(Frequency, Duration)

Parameters

Frequency

Type: Integer

The frequency of the beep (100Hz-10000Hz).

Duration

Type: Integer

The duration of the beep in milliseconds.

Expand image Remarks

The BEEP function is not supported in the RoleTailored client.

Expand image See Also

Reference

Dialog Data Type


CLOSE Function (Dialog)

CLOSE Function (Dialog)
See Also
CollapseAll image

Closes a dialog window that has been opened by OPEN Function (Dialog).

Dialog.CLOSE

Parameters

Dialog

Type: Dialog

The Dialog variable that you are closing.

Expand image Remarks

If CLOSE is used on a dialog window that is not open, a run-time error will occur.

The dialog windows of an object are automatically closed when the object terminates.

Expand image See Also

Reference

Dialog Data Type


CONFIRM Function (Dialog)

CONFIRM Function (Dialog)
See Also Example
CollapseAll image

Creates a dialog box that prompts the user for a yes or no answer. The dialog box is centered on the screen for you.

Ok := Dialog.CONFIRM(String [, Default] [, Value1] ,...)

Parameters

String

Type: Code or text constant

Specifies the string that is displayed in the dialog box. Use a backslash (\) to indicate a new line. The string can be a text constant that is enabled for multilanguage functionality. For more information, see Working with Multilanguage Functionality.

Default

Type: Boolean

Specifies the default button. If you do not specify a default, then No is used as the default.

Expand image Property Value/Return Value

Type: Boolean

true if you entered Yes; otherwise, false.

This return parameter reflects the user's selection.

Expand image Remarks

The message window is sized for you. The height of the window corresponds to the number of lines and the width corresponds to the length of the longest line.

We recommend that you always end CONFIRM messages with a question mark. For more information about best practices for end-user messages, see Progress Windows, MESSAGE, ERROR and CONFIRM Functions.

Expand image Example

In the following example, the Dialog.CONFIRM function prompts the user for a Yes or No answer. This code example requires that you create the following variables.

Name | Data type
Question | Text
Answer | Boolean

This code example requires that you create the following text constants in the C/AL Globals window.

Name | ConstValue
Text000 | Leave without saving changes?
Text001 | You selected %1.
CopyCode image Copy Code
Question := Text000;
Answer := Dialog.CONFIRM(Question, TRUE);
MESSAGE(Text001, Answer);

Expand image See Also

Reference

Dialog Data Type


ERROR Function (Dialog)

ERROR Function (Dialog)
See Also Example
CollapseAll image

Displays an error message and ends the execution of C/AL code.

ERROR(String [, Value1, …])

Parameters

String

Type: Text constant or code

This string contains the text of the error message you want to display to the user. Use percent signs (%) or number signs (#) to insert variable values into the string. Place the percent or number signs where you want to substitute the variable value. The string can be a text constant that is enabled for multilanguage functionality. For more information, see Working with Multilanguage Functionality.

Value1,…

Type: Any

Any variable or expression to be inserted in String. You can insert up to 10 values.

For '#'-type fields, the value is truncated according to the total number of number-sign characters in String. For '%'-type fields, the full length of the value is printed.

Expand image Remarks

The window is automatically sized to hold the longest line of text and total number of lines.

Expand image Programming Guidelines

We recommend the following guidelines for error messages:

  • Describe what is wrong and how to solve the problem.

  • Write a short descriptive message. Do not use more words than necessary.

  • Always end the error message with a period.

  • Use a text constant for the text of the message.

For more information, see Progress Windows, MESSAGE, ERROR and CONFIRM Functions.

Expand image Example

This example shows how to use the ERROR function. The code example requires you to create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
AccountNo | Integer
Text Constant | ENU Value
Text000 | Finance Account #1#### must not be blocked.
Text001 | Placeholder message.
CopyCode image Copy Code
AccountNo := 1230;
// The execution stops when the error statement is executed
// and all following statements will never be executed.
ERROR(Text000, AccountNo);
MESSAGE(Text001); // This line is not executed.

The error window displays the following:

Finance Account 1230 must not be blocked.

The ERROR function causes execution of C/AL code to stop. The MESSAGE function is never executed.

Expand image See Also

Reference

Dialog Data Type
MESSAGE Function (Dialog)

Concepts

Progress Windows, MESSAGE, ERROR and CONFIRM Functions


INPUT Function (Dialog)

INPUT Function (Dialog)
See Also
CollapseAll image

Reads what a user enters into a field in a window. The input is returned in a variable. This function also returns a number which identifies the next input field in the window.

NewControlID := Dialog.INPUT([ControlID][,Variable])

Parameters

ControlID

Type: Integer

This number identifies the field in the dialog window.

Variable

Type: Any

A variable that may be edited in the dialog window.

Expand image Property Value/Return Value

Type: Integer

Specifies the control ID of the next field in the window. If the user presses ESC to leave the window, the window will close, the calling C/AL code will terminate, and zero is returned.

Expand image Remarks

The INPUT function is not supported in the RoleTailored client.

Expand image See Also

Reference

Dialog Data Type


MESSAGE Function (Dialog)

MESSAGE Function (Dialog)
See Also Example
CollapseAll image

Displays a text string in a message window.

MESSAGE(String [, Value1, …])

Parameters

String

Type: Code or text constant

This string contains the text you want the system to display in the message window. Use a backslash (\) to start a new line. Use percent signs (%) to insert variable values into the string. Place the percent where you want the system to substitute the variable value. The string can be a text constant that is enabled for multilanguage functionality. For more information, see Working with Multilanguage Functionality.

Value1, …

Type: Any

Any type of C/AL variable you want to insert into String. You can insert up to 10 values.

Expand image Remarks

When a message statement in the C/AL code is executed, the message is not immediately displayed. Instead, it is displayed after the C/AL code is finished executing or after the C/AL code pauses to wait for user interaction.

The window is automatically sized to hold the longest line of text and the total number of lines.

Expand image Programming Guidelines

We recommend the following guidelines for messages:

  • Always end a message with a period.

  • Supply the user with a message when the system has finished performing a task.

  • Write the message in past tense.

For more information, see Progress Windows, MESSAGE, ERROR and CONFIRM Functions.

Expand image Example

This example shows how to use the MESSAGE function.

This code requires you to create the following variables.

Variable | Data type
Text | Text
Number | Decimal

This code requires you to create the following text constants.

Text constant | ENU value
Text000 | You can use message windows to display text and numbers: \
Text001 | The number:
Text002 | The text:
CopyCode image Copy Code
Text := 'ABCDE';
Number := 12345.678;
// The backslash indicates a new line.
// You can concatenate strings using the + operator.
// You can insert variable values using the % symbol.
MESSAGE(Text000 + Text001 + '%1\' +Text002 + '%2', Number, Text);

The message window reads:

You can use message windows to display text and numbers:

The number: 12,345.678

The text: ABCDE

Expand image See Also

Reference

Dialog Data Type


OPEN Function (Dialog)

OPEN Function (Dialog)
See Also Example
CollapseAll image

Opens a dialog window.

Dialog.OPEN(String [, Variable1],...)

Parameters

Dialog

Type: Dialog

After you define this variable, you can open the dialog and then use other dialog functions.

String

Type: Text constant or code

This string contains the text that you want to display in the window. Use a backslash (\) to start a new line. Use number signs (#) to insert variable values into the string. Place the number signs where you want to substitute the variable value. Place a number in the part of the string where a variable value will be substituted (for example, #1####) to be able to reference this field for updating.

If you use @ characters instead of # characters, then the variable value is used as a percentage and is displayed as a progress indicator. The value that is displayed is the percentage from 0 to 9999.

The number of # or @ characters in the string indicates the length of the field or progress indicator.

You can update the fields using the UPDATE Function (Dialog) or INPUT Function (Dialog) or by letting the user edit the values.

Variable1

Type: Any

Use these optional parameters to specify variables for field1, field2, and so on.

Expand image Remarks

Dialog windows opened by an object are closed when the object terminates.

Dialog windows are automatically sized to hold the longest line of text and the total number of lines.

We recommend the following guidelines:

  • Enter messages as text constants.

  • Write messages using active voice. For example, write “Processing items” instead of writing “Items are being processed.”

  • Align the # and @ fields to the left with at least one space character between the text and the variable.

Expand image Example

This example shows how to use the dialog.OPEN function.

This code example requires that you create the following variables.

Name | Data type
AccountInfo | Text
AccNo | Integer
TotSum | Integer
MyDialog | Dialog
Next | Integer

This example requires that you create the following text constants.

Name | ConstValue
Text000 | Account no. #1######,\
Text001 | has a total of $ #2######
CopyCode image Copy Code
AccountInfo := Text000 + Text001;
AccNo := 5634;
TotSum := 1000;
MyDialog.OPEN(AccountInfo, AccNo, TotSum);
REPEAT
  // Do some processing.
  …
  MyDialog.UPDATE(); // Update the fields.
UNTIL Next = 0;
MyDialog.CLOSE()

The dialog window opens and displays this text:

Account no.. . . . . 5634,

has a total of $. . . . . . . 1000

This shows that the values of the AccNo and TotSum variables have been formatted into the '#'-fields.

Expand image See Also

Reference

Dialog Data Type


STRMENU Function (Dialog)

STRMENU Function (Dialog)
See Also Example
CollapseAll image

Creates a menu window that displays a series of options.

OptionNumber := Dialog.STRMENU(OptionString [, DefaultNumber] [, Instruction])

Parameters

OptionString

Type: Code or text constant

A comma-separated string. Each substring in OptionString denotes an option on the menu. The string can be a text constant that is enabled for multilanguage functionality. For more information, see Working with Multilanguage Functionality.

DefaultNumber

Type: Integer

Use this optional parameter to determine a default option, which is highlighted. The options are numbered 1, 2, 3, 4, and so on.

If you omit this optional parameter, the first option (1) is used as the default.

Instruction

Type: Code or text constant

Use this optional parameter to add a description to the option values.

Expand image Property Value/Return Value

Type: Integer

The number of the menu option that the user selected. If the user presses ESC to exit the menu, zero (0) is returned.

Expand image Example

This example shows how to use the Dialog.STRMENU function.

This code example requires you to create the following text constants and variables in the C/AL Globals window.

Text Constant | Const Value ENU Value
Text000 | 'Save,Delete,Exit,Find ...'
Text001 | 'You selected option%1.'
Text002 | 'Choose one of the following options:'
Variable | Data Type | Length
Options | Text | 30
Selected | Integer |
CopyCode image Copy Code
Options := Text000
// Sets the default to option 3
Selected := Dialog.STRMENU(Options, 3, Text002);
MESSAGE(Text001, Selected);

The menu window displays the following text:

Choose one of the following optons:

Save

Delete

Exit

Find …

Option 3, Exit, is highlighted. The option that the user selects is stored in the variable Selected and the following message is displayed:

You selected option 3.

Expand image See Also

Reference

Dialog Data Type


UPDATE Function (Dialog)

UPDATE Function (Dialog)
See Also Example
CollapseAll image

Updates the value of a '#'-or '@' field in the current window.

Dialog.UPDATE([Number] [, Value1])

Parameters

Dialog

Type: Dialog

The dialog you want to update.

Number

Type: Integer

Each '#' or '@' field has a specific number. The Number argument tells the system into which field it should insert Value. If you omit this parameter, all '#' or '@' fields in the current window are updated.

Value

Type: Any

This value (or expression) can be any simple C/AL data type such as Boolean, option, integer, decimal date, time, text and code. If you omit this value, then the value from the variable in the OPEN Function (Dialog) call is used.

Expand image Remarks

When you have a function that contains Dialog.UPDATE(Number,Value) and the value is a variant, you must format the text constant to ensure that the variant type can understand the text constant.

In C/SIDE, the text constant is read as type AL_TEXTCONST, which cannot be interpreted by the variant.

You can use the FORMAT Function (Code, Text) to convert the text constant to a string type, which can be interpreted and displayed by the variant.

Expand image Example

The following example shows how to update '#' fields in a window.

This code example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
AccountInfo | Text | 1024
AccountNo | Integer |
TotalSum | Decimal |
MyDialog | Dialog |
Text constant name | Constant value
Text000 | Account no. #1######\
Text001 | shows a total of $ #2######
CopyCode image Copy Code
AccountInfo := Text000 + Text001;
AccountNo := 5634;
TotalSum := 1000;
MyDialog.OPEN(AccountInfo); // Opens a window with '#'-fields.

SLEEP(5000);
MyDialog.UPDATE(1, AccountNo); // Fills in field 1.
SLEEP(5000);
MyDialog.UPDATE(2, TotalSum); // Fills in field 2.
SLEEP(5000);

When the dialog window first opens, the following information is displayed:

Account no. . . . . shows a total of $. . . . . . .

After the first SLEEP call, the value of the AccountNo variable is inserted. After the second SLEEP call, the value of the TotalSum variable is inserted.

Expand image See Also

Reference

Dialog Data Type
OPEN Function (Dialog)


YIELD Function (Dialog)

YIELD Function (Dialog)
See Also
CollapseAll image

Passes control to the operating system, specifically DOS/Windows 3.x, so it can process events. After the operating system finishes, you regain control.

Yield

Expand image Remarks

If you do not want your C/AL code to completely tie up the system for long periods of time, you can insert this function periodically so other programs can run. For example, if you are creating a report which needs to read many records, you may want to occasionally use this function so other users can continue to work.

This function is not supported in the RoleTailored client.

Expand image See Also

Reference

Dialog Data Type


Error Handling

Error Handling

This section contains the following topics:

  • CLEARLASTERROR Function

  • GETLASTERRORTEXT Function


CLEARLASTERROR Function

CLEARLASTERROR Function

Removes the last error message from memory.

CLEARLASTERROR

Expand image Remarks

You can set up Microsoft Dynamics NAV so that it keeps running even if a run-time error occurs. You can use the GETLASTERRORTEXT Function to determine whether an error has occurred and to see the actual text in the last error message that was generated. You can then use the CLEARLASTERROR function to remove the last error message from memory. If you subsequently call the GETLASTERRORTEXT function, an empty string is returned.


GETLASTERRORTEXT Function

GETLASTERRORTEXT Function

Returns the text that was contained in the last error message that was displayed.

String := GETLASTERRORTEXT

Expand image Property Value/Return Value

Type: Text

The text string that was contained in the last error message that was displayed by Microsoft Dynamics NAV.

The string cannot exceed the maximum string length specified in Microsoft Dynamics NAV. This is currently 1024.

If no error has occurred, the function returns an empty string.

Expand image Remarks

You can set up Microsoft Dynamics NAV so that it keeps running even if a run-time error occurs. You can use this function to determine whether an error has occurred and to see the actual text in the last error message that was generated. You can also use the CLEARLASTERROR function to remove the last error message from memory. If you then call GETLASTERRORTEXT, an empty string is returned.

Expand image See Also

Reference

CLEARLASTERROR Function


FieldRef Data Type

FieldRef Data Type

This complex data type identifies a field in a table and gives you access to this field. The fieldref object can refer to any field in any table in the database.

Expand image See Also

Reference

ACTIVE Function (FieldRef)
CALCFIELD Function (FieldRef)
CALCSUM Function (FieldRef)
CAPTION Function (FieldRef)
CLASS Function (FieldRef)
FIELDERROR Function (FieldRef)
GETFILTER Function (FieldRef)
GETRANGEMAX Function (FieldRef)
GETRANGEMIN Function (FieldRef)
LENGTH Function (FieldRef)
NAME Function (FieldRef)
NUMBER Function (FieldRef)
OPTIONCAPTION Function (FieldRef)
OPTIONSTRING Function (FieldRef)
RECORD Function (FieldRef)
RELATION Function (FieldRef)
SETFILTER Function (FieldRef)
SETRANGE Function (FieldRef)
TESTFIELD Function (FieldRef)
TYPE Function (FieldRef)
VALIDATE Function (FieldRef)
VALUE Function (FieldRef)


ACTIVE Function (FieldRef)

ACTIVE Function (FieldRef)
See Also
CollapseAll image

Use this function to check whether the field that is currently selected is enabled.

Ok := FieldRef.ACTIVE

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: Boolean

true if the field is enabled; otherwise, false.

Expand image Remarks

Each field in a record can be set as enabled or disabled in the table description.

You cannot use a disabled field because disabled fields cannot contain data.

This function is similar to the FIELDACTIVE Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type


CALCFIELD Function (FieldRef)

CALCFIELD Function (FieldRef)
See Also
CollapseAll image

Use this function to update FlowFields in a record.

[Ok :=] FieldRef.CALCFIELD

Parameters

FieldRef

Type: FieldRef

The fieldref of the FlowField that you want to update.

Expand image Property Value/Return Value

Type: Boolean

true if FlowField has been calculated; otherwise, false.

Expand image Remarks

FlowFields are virtual fields. The values in these fields are not saved in the table.

This means that you must use the CALCFIELDS function to update them. For example, if you retrieve a record using the FIND Function (RecordRef) and NEXT Function (RecordRef) functions, the FlowFields in those records are set to zero (0). Then, you can call FieldRef.CALCFIELD, to calculate the value in one of the FlowFields.

When a FlowField is a direct source expression of a control on a form or a report, the calculation is automatically performed.

You can also use the CALCFIELDS function to calculate binary large objects (BLOBs). For more information, see BLOB Data Type.

This function is similar to the CALCFIELDS Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type


CALCSUM Function (FieldRef)

CALCSUM Function (FieldRef)
See Also
CollapseAll image

Use this function to calculate the total of SumIndexFields in a table.

[Ok :=] FieldRef.CALCSUM

Parameters

FieldRef

type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value and if the field is not SumIndexFields, a run-time error occurs. If you include a return value, you must handle any errors.

Expand image Remarks

This function is similar to the CALCSUMS Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type


CAPTION Function (FieldRef)

CAPTION Function (FieldRef)
See Also
CollapseAll image

Use this function to return the current caption of a field referred to by a fieldref as a string.

Caption := FieldRef.CAPTION

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: text or code

CaptionML or Name property as text or code.

Expand image Remarks

CAPTION returns the caption of a field. CAPTION first looks for a CaptionML Property property.

If it does not find one it will use the Name Property. This means that CAPTION is enabled for multilanguage functionality.

This function is similar to the FIELDCAPTION Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type

Concepts

Working with Multilanguage Functionality


CLASS Function (FieldRef)

CLASS Function (FieldRef)
See Also Example
CollapseAll image

Use this function to return the value of the FieldClass Property of the field that is currently selected.

This function returns an error if no field is selected.

Class := FieldRef.CLASS

Parameters

FieldRef

Type: FieldRef

Refers to the current field.

Expand image Property Value/Return Value

Type: Option

The field class of the field.

Expand image Remarks

The FieldRef refers to the field that you are interested in.

The CLASS function returns the class as an Option. However, you cannot assign the class to an Option variable directly. Instead, you must use the EVALUATE Function. The EVALUATE function has a variable parameter to which the value is assigned and a string parameter. You use the FORMAT function to convert the result of the FieldRef.CLASS function to Text, and then use the EVALUATE function to convert the Text to an Option.

Expand image Example

In this example, the return value of the CLASS function is converted to Text and then converted to an Option. This example requires that you create the following variables.

Name | DataType
OptionVar | Option
FldRef | FieldRef

The value of the OptionString property of OptionVar is Normal,FlowFilter,FlowField.
CopyCode image Copy Code
EVALUATE(OptionVar,FORMAT(FldRef.CLASS));

In this example, the return value of the CLASS function is converted to Text and then converted to an Option. This example uses the Field virtual table instead of an Option variable. The Field virtual table has a Class field, which is an Option and already has the correct OptionString.

This example requires that you create the following variables.

Name | DataType | Subtype
FieldRec | Record | Field
FldRef | FieldRef |
CopyCode image Copy Code
EVALUATE(FieldRec.Class,FORMAT(FldRef.CLASS));

Expand image See Also

Reference

FieldRef Data Type


FIELDERROR Function (FieldRef)

FIELDERROR Function (FieldRef)
See Also
CollapseAll image

Use this function to stop the execution of the code (cause a run-time error) and create an error message for a field.

FieldRef.FIELDERROR([Text])

Parameters

FieldRef

Type: fieldref

Refers to the field for which you want to create an error message.

Text

Type: text or code

Use this optional parameter to include the text of the error message. If this parameter is not present, default text will be used.

Expand image Remarks

Similar to a run-time error, this function causes any transaction to be aborted automatically.

This function is similar to the FIELDERROR Function for the Record data type. For examples, see FIELDERROR Function (Record).

Expand image Programming Guidelines

We recommend the following guidelines for error messages:

  • Describe what is wrong and how to solve the problem.

  • Write a short descriptive message. Do not use more words than necessary.

  • Note that a period is automatically inserted at the end of a FIELDERROR.

  • Use a text constant for the Text parameter.

For more information, see Progress Windows, MESSAGE, ERROR and CONFIRM Functions.

Expand image See Also

Reference

FieldRef Data Type


GETFILTER Function (FieldRef)

GETFILTER Function (FieldRef)
See Also
CollapseAll image

Use this function to return the filter that is currently applied to the field referred to by fieldref.

String := FieldRef.GETFILTER

Parameters

FieldRef

Type: fieldref

Refers to the field for which you want to return the filter.

Expand image Property Value/Return Value

Type: text

This string contains the filter that is applied to the field in the record.

Expand image Remarks

See also GETFILTERS Function (RecordRef), SETFILTER Function (FieldRef), and SETRANGE Function (FieldRef).

This function is similar to the GETFILTER Function (Record)function.

Expand image See Also

Reference

FieldRef Data Type


GETRANGEMAX Function (FieldRef)

GETRANGEMAX Function (FieldRef)
See Also
CollapseAll image

Use this function to return the maximum value in a range for a field.

Value := FieldRef.GETRANGEMAX

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: depends on the field referred to by the fieldref.

Contains the maximum value of the range set for the field referred to by the fieldref.

The type of value must match the type of the field referred to by the fieldref.

Expand image Remarks

This function is similar to the GETRANGEMAX Function (Record) function.

Expand image See Also

Reference

GETRANGEMIN Function (FieldRef)
FieldRef Data Type


GETRANGEMIN Function (FieldRef)

GETRANGEMIN Function (FieldRef)
See Also
CollapseAll image

Use this function to return the minimum value in a range for a field.

Value := FieldRef.GETRANGEMIN

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: text constant or code

Contains the minimum value of the range set for the field referred to by the fieldref.

The data type of value must match the data type of the field referred to by the fieldref.

Expand image Remarks

This function is similar to the GETRANGEMIN Function (Record) function.

Expand image See Also

Reference

GETRANGEMAX Function (Record)
FieldRef Data Type


LENGTH Function (FieldRef)

LENGTH Function (FieldRef)
See Also
CollapseAll image

Use this function to return the maximum size of the field (the size specified in the DataLength property of the field). This function is usually used for finding the defined length of code and text fields.

Length := FieldRef.LENGTH

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Return Value

Type: integer

The defined length of the field.

Expand image Remarks

For Text and Code fields this function returns the defined length. For other types of fields, it returns the fixed byte size, for example, Integer fields returns 4.

Expand image See Also

Reference

FieldRef Data Type


NAME Function (FieldRef)

NAME Function (FieldRef)
See Also
CollapseAll image

Use this function to return the name of a field as a string.

Name := FieldRef.NAME

Parameters

FieldRef

The fieldref of the field in the record.

Expand image Property Value/Return Value

Type: text constant or code

The name of the field given as input.

Expand image Remarks

The CAPTION Function (FieldRef) function retrieves the Caption Property property of a field. If you want to enable your application for multilanguage functionality now or in the future, you must use the FIELDCAPTION Function (Record) instead.

This function is similar to the FIELDNAME Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type

Concepts

Working with Multilanguage Functionality


NUMBER Function (FieldRef)

NUMBER Function (FieldRef)
See Also
CollapseAll image

Use this function to return the number of a field as a string.

No := FieldRef.NUMBER

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: Integer

The number of the table or of the field.

Expand image Remarks

This function is similar to the FIELDNO Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type


OPTIONCAPTION Function (FieldRef)

OPTIONCAPTION Function (FieldRef)
See Also
CollapseAll image

Use this function to return the option caption of the field that is currently selected.

OptionCaption := FieldRef.OPTIONCAPTION

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: text

The option caption of the field.

Expand image Remarks

The option caption of the field is returned as a comma separated string.

If the field is not an option, an empty string is returned.

This function returns an error if no field is selected.

Expand image See Also

Reference

FieldRef Data Type


OPTIONSTRING Function (FieldRef)

OPTIONSTRING Function (FieldRef)
See Also
CollapseAll image

Use this function to return the list of options that are available in the field that is currently selected.

OptionString := FieldRef.OPTIONSTRING

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: text

The list of options that is available in the field.

Expand image Remarks

All the options for this field are returned as a comma separated string.

This function returns an error if no field is selected.

If the field is not an option an empty string is returned

Expand image See Also

Reference

FieldRef Data Type


RECORD Function (FieldRef)

RECORD Function (FieldRef)
See Also
CollapseAll image

Use this function to return the recordref of the field that is currently selected.

This function returns an error if no field is selected.

RecordRef := FieldRef.RECORD

Parameters

FieldRef.

Type: fieldref

Refers to the current field.

Expand image Return Value

Type: recordref

The recordref of the field that is currently selected.

See also RecordRef Data Type.

Expand image See Also

Reference

FieldRef Data Type


RELATION Function (FieldRef)

RELATION Function (FieldRef)
See Also
CollapseAll image

Use this function to find the table relationship of a given field.

TableNumber := FieldRef.RELATION

Parameters

FieldRef

Type: fieldref

The fieldref that refers to the field for which you want to find the table relationship.

Expand image Property Value/Return Value

Type: integer

The number of the table that has a relationship with the field referred to by fieldref.

This relationship is set up through the properties.

Expand image Remarks

You can use this function for several purposes such as to determine lookups or to check to see if you have permission to read from a table.

This function is similar to the RELATION Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type


SETFILTER Function (FieldRef)

SETFILTER Function (FieldRef)
See Also
CollapseAll image

Use this function to assign a filter to a field you specify.

FieldRef.SETFILTER(String [, Value],...)

Parameters

FieldRef

Type: fieldref

The fieldref that refers to the field that you want to place a filter on.

String

Type: text or code

The filter expression. A valid expression consists of alphanumeric characters and one or more of the following operators: <, >, *, &, |, and =. You can use replacement fields (%1, %2, and so on) to insert values at run-time.

Value

Type: any

Replacement values to insert in replacement fields in the filter expression. The data type of Value must match the type of Field.

Expand image Remarks

If the function is called with a field for which a filter already exists, the filter is removed before a new one is set. You can construct filters using the following operators.

Operator | Description
.. | Range
& | And
| | Or
< | Less than
<= | Less than or equal to
> | Greater than
>= | Greater than or equal to
<> | Different from
* | Forms a part of value
@ | Case-insensitive

This function is similar to the SETFILTER Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type


SETRANGE Function (FieldRef)

SETRANGE Function (FieldRef)
See Also
CollapseAll image

Use this function to set a simple filter on a field, such as a single range or a single value.

FieldRef.SETRANGE([FromValue] [, ToValue])

Parameters

FieldRef

Type: fieldref

The fieldref that refers to the field that you want to place a filter on.

FromValue

Type: any

The lower limit of the range. The data type of FromValue must match the data type of the field referred to by the fieldref.

ToValue

Type: any

The upper limit of the range. If you omit this parameter, the FromValue you specified is used. The data type of ToValue must match the data type of the field referred to by the FieldRef.

Expand image Remarks

The SETRANGE function provides a quick way to set a simple filter on a field.

If you call this function with a field that already has a filter, that filter is removed before the new filter is set.

If you omit all of the optional parameters, all filters set for that field are removed.

The SETRANGE function fails if no field is selected.

This function is similar to the SETRANGE Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type


TESTFIELD Function (FieldRef)

TESTFIELD Function (FieldRef)
See Also
CollapseAll image

Use this function to see if the contents of a field match a given value. If the contents differ from the given value, an error message displays.

FieldRef.TESTFIELD([Value])

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Value

Type: any

The value that you want to compare with the contents of the field referred to by

fieldref. The data type of Value must match the type of the field.

If you include Value and the contents of the field do not match, an error message is displayed.

If you omit Value and the content of the field is zero or blank (empty string), an error message is displayed.

Expand image Remarks

This function is similar to the TESTFIELD Function (Record) function.

Expand image See Also

Reference

FieldRef Data Type


TYPE Function (FieldRef)

TYPE Function (FieldRef)
See Also
CollapseAll image

Use this function to return the data type of the field that is currently selected.

Type := FieldRef.TYPE

Parameters

FieldRef

Type: fieldref

Refers to the current field.

Expand image Property Value/Return Value

Type: The data type of the field.

Expand image See Also

Reference

FieldRef Data Type


VALIDATE Function (FieldRef)

VALIDATE Function (FieldRef)
See Also
CollapseAll image

Use this function to enter a new value into a field and have the new value validated by the properties and code that have been defined for that field.

FieldRef.VALIDATE([NewValue])

Parameters

FieldRef

Type: fieldref

Refers to the current field.

NewValue

Type: must be compatible with the data type of the field referred to by the fieldref.

The value to insert in the field.

Expand image Remarks

The VALIDATE function first checks any TableRelation Property, and then executes the OnValidate (Fields) Trigger of the field.

If you omit NewValue, the function validates the current value.

This function is similar to the VALIDATE Function (Record).

Expand image See Also

Reference

FieldRef Data Type


VALUE Function (FieldRef)

VALUE Function (FieldRef)
See Also
CollapseAll image

Use this function to set or get the value of the field that is currently selected.

This function returns an error if no field is selected.

[CurrValue :=] FieldRef.VALUE([NewValue])

Parameters

FieldRef

Type: fieldref

Refers to the current field.

NewValue

Type: variant

The new value that you want to set for the field.

Expand image Property Value/Return Value

Type: variant

The current value of the field.

Expand image Remarks

If you omit NewValue, the function returns the current value of the field.

If you want to format the value of a fieldref you must use FORMAT(FieldRef) instead of FORMAT(FieldRef.VALUE).

Expand image See Also

Reference

FieldRef Data Type


File Data Type

File Data Type

The FILE data type gives access to files. Files can be opened in text or binary mode. For more information, see TEXTMODE Function (File).

You can read from or write to a file by creating input and output streams, respectively. To do so, use the CREATEINSTREAM Function (File) and CREATEOUTSTREAM Function (File). For more information, see InStream and OutStream Data Types.

Expand image Differences Between the Classic Client and RoleTailored Client

If you are running on the RoleTailored client and do not specify the uniform naming convention (UNC) path of a file, FILE functions access files on Microsoft Dynamics NAV Server.

If you are running on the Classic client and do not specify the UNC path of a file, FILE functions access files on the client.

Expand image See Also

Reference

CLOSE Function (File)
COPY Function (File)
CREATE Function (File)
CREATEINSTREAM Function (File)
CREATEOUTSTREAM Function (File)
CREATETEMPFILE Function (File)
DOWNLOAD Function (File)
DOWNLOADFROMSTREAM Function (File)
ERASE Function (File)
EXISTS Function (File)
GETSTAMP Function (File)
LEN Function (File)
NAME Function (File)
OPEN Function (File)
POS Function (File)
QUERYREPLACE Function (File)
READ Function (File)
RENAME Function (File)
SEEK Function (File)
SETSTAMP Function (File)
TEXTMODE Function (File)
TRUNC Function (File)
UPLOAD Function (File)
UPLOADINTOSTREAM Function (File)
WRITE Function (File)
WRITEMODE Function (File)


CLOSE Function (File)

CLOSE Function (File)
See Also
CollapseAll image

Closes a file that has been opened by the OPEN Function (File).

File.CLOSE

Parameters

File

Type: File

Specifies the file.

Expand image Remarks

If the file is not open, a run-time error will occur.

Expand image See Also

Reference

File Data Type


COPY Function (File)

COPY Function (File)
See Also
CollapseAll image

Use this function to copy a file.

[Ok :=] File.COPY(FromName, ToName)

Parameters

FromName

Type: text or code

The name of the file that you want to make a copy of, including its path. When you enter the path, keep in mind these shortcuts:

  • You can omit the drive designation, if the file is located on the current drive.

  • You can omit the full path, if the file is located in the current directory.

  • You can enter only the subdirectory name, if the file is located in a subdirectory of the current directory.

ToName

Type: text or code

The name that you want to assign to the copy, including its path. When you enter the path, keep in mind these shortcuts:

  • You can omit the drive designation, if the file is located on the current drive.

  • You can omit the full path, if the file is located in the current directory.

  • You can enter only the subdirectory name, if the file is located in a subdirectory of the current directory.

Expand image Property Value/Return Value

Type: Boolean

This optional return parameter shows you whether the file was copied.

Expand image Remarks

If you do not use the return value, and the file cannot be copied, a run-time error will occur. If you do include the return value in your code, you must handle any errors yourself.

Expand image Example 1

CopyCode image Copy Code
File.COPY('c:\data\oldfile','a:\newfile')

To copy a file on your c: drive named oldfile to a file called newfile on drive a:, you would use the function shown in the preceding example.

Expand image Example 2

CopyCode image Copy Code
if File.COPY('c:\data\oldfile', 'a:\newfile') then
... // continue your program
else
... // else handle the error

If the file cannot be copied, a run-time error will occur. You can avoid this by using the return value shown in the preceding example.

Expand image See Also

Reference

File Data Type


CREATE Function (File)

CREATE Function (File)
See Also
CollapseAll image

Creates and opens an ASCII or binary file. If the file exists, it will be truncated and then opened.

[Ok := ] File.CREATE(Name)

Parameters

File

Type: file

Specifies the file.

Name

Type: text or code

The name of the file, including the path. The following rules apply:

  • You can omit the drive designation if the file is located on the current drive.

  • You can omit the full path if the file is located in the current directory.

  • You can enter only the subdirectory name if the file is located in a subdirectory of the current directory.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether the file was created.

true if the file was created; otherwise, false.

Expand image Remarks

Always call the TEXTMODE Function (File) before you use the CREATE function or the OPEN Function (File).

If TEXTMODE is true and you read or write to the file, text is placed in the buffer.

If TEXTMODE is false, binary information is placed in the buffer.

Differences Between the Classic Client and RoleTailored Client

If you are running the RoleTailored client and you call CREATE on a file variable that refers to an open file, the function will not automatically close the existing file and create the new file. You must explicitly call the CLOSE Function (File) to close the existing file. Otherwise, a run-time error occurs.

If you are running the Classic client and you call CREATE on a file variable that refers to an open file, the function will CLOSE the existing file and CREATE the new file. A run-time error does not occur.

Expand image See Also

Reference

File Data Type


CREATEINSTREAM Function (File)

CREATEINSTREAM Function (File)
See Also
CollapseAll image

Creates an InStream object for a file. This enables you to import or read data from the file.

File.CreateInStream(Stream)

Parameters

File

Type: File

Use this variable to refer to the file.

Stream

The InStream object type that has been created.

For more information, see Code Example for Streams

Expand image See Also

Reference

File Data Type


CREATEOUTSTREAM Function (File)

CREATEOUTSTREAM Function (File)
See Also
CollapseAll image

Creates an OutStream object for a file. This enables you to export or write data to the file.

File.CreateOutStream(Stream)

Parameters

File

Type: File

Use this variable to refer to the file.

Stream

The OutStream object type that has been created.

For more information, see Code Example for Streams.

Expand image See Also

Reference

File Data Type


CREATETEMPFILE Function (File)

CREATETEMPFILE Function (File)
See Also Example
CollapseAll image

Creates a temporary file. This enables you to save data of any format to a temporary file. This file has a unique name and will be stored in a temporary file folder.

File.CreateTempFile

Parameters

File

Type: File

Use this variable to refer to the file.

Expand image Remarks

You can use this function with NAME Function (File) and CLOSE Function (File).

This function is not supported in the RoleTailored client.

Expand image Example

This example creates a temporary file with the text Hello and then deletes the file by using the File.CLOSE function. This example requires that you create the following variable.

Variable | Data type
FileName | File
CopyCode image Copy Code
FileName.CREATETEMPFILE:
FileName.WRITE('Hello');
FileName.CLOSE;

Expand image See Also

Reference

File Data Type


DOWNLOAD Function (File)

DOWNLOAD Function (File)
See Also Example
CollapseAll image

Sends a file from a Microsoft Dynamics NAV service to a RoleTailored client.

[Ok :=] DOWNLOAD(FromFile, DialogTitle, ToFolder, ToFilter, ToFile)

Parameters

FromFile

Type: text

The name of the file that you want to download to the client.

DialogTitle

Type: text

The title that you want to display on the dialog box.

ToFolder

Type: text

The name of the folder that is displayed in the dialog box. This is the default value, which can be changed.

ToFilter

Type: text

The type of file that is displayed in the dialog box. This is the default value, which can be changed.

ToFile

Type: variant

The file name that is shown in the dialog box. This is the default , which can be changed.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, a run-time error occurs if the file cannot be found. If you include a return value, it is assumed that you will handle any errors.

true if the file was downloaded; otherwise, false.

Expand image Remarks

In the new architecture, the business logic is run on the middle-tier server and not on the client.

This means that in Microsoft Dynamics NAV, files are created on the Microsoft Dynamics NAV service and not locally on the client computer as is the case in the Classic client. When you write code for the application, you must therefore remember where the files are created.

UPLOAD Function (File) and UPLOADINTOSTREAM Function (File) are used to send a file from a RoleTailored client to a Microsoft Dynamics NAV service.

DOWNLOAD Function (File) and DOWNLOADFROMSTREAM Function (File) are used to send a file from a Microsoft Dynamics NAV service to a RoleTailored client.

We recommend that you use the functions in Codeunit 419, 3-Tier Automation Mgt., to upload and download files.

Expand image Example

This example shows how to use the DOWNLOAD function. It requires that you create the following variable.

Variable | Data type
ToFile | Text
CopyCode image Copy Code
ToFile := 'ToFile.txt';
DOWNLOAD(‘FromFile.txt’,‘Download file’,’C:\’,’Text file(*.txt)|*.txt’,ToFile)

Expand image See Also

Reference

File Data Type


DOWNLOADFROMSTREAM Function (File)

DOWNLOADFROMSTREAM Function (File)
See Also Example
CollapseAll image

Sends a file from a Microsoft Dynamics NAV Server to a RoleTailored client.

[Ok :=] DOWNLOADFROMSTREAM(VarInstream, DialogTitle, ToFolder, ToFilter, ToFile)

Parameters

VarInStream

Type: variant

An InStream that you want to use to send the data in a file on Microsoft Dynamics NAV Server to a file on a RoleTailored client.

DialogTitle

Type: text

The title that you want to display on the dialog box.

ToFolder

Type: text

The name of the folder that is displayed in the dialog box.

ToFilter

Type: text

The type of file that is displayed in the dialog box.

ToFile

Type: variant

The name of the file that is displayed in the dialog box.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, a run-time error occurs if the record cannot be found. If you include a return value, it is assumed that you will handle any errors.

true if the file was downloaded; otherwise, false.

Expand image Remarks

In the new architecture the business logic is run on the middle-tier server and not on the client.

This means that in Microsoft Dynamics NAV, files are created on the Microsoft Dynamics NAV service and not locally on the client computer as is the case in the Classic client. When you write code for the application, you must therefore remember where the files are created.

Use UPLOAD Function (File) and UPLOADINTOSTREAM Function (File) to send a file from a RoleTailored client to a Microsoft Dynamics NAV service.

Use DOWNLOAD Function (File) and DOWNLOADFROMSTREAM Function (File) to send a file from a Microsoft Dynamics NAV service to a RoleTailored client.

We recommend that you use the functions in Codeunit 419, 3-Tier Automation Mgt., to upload and download files.

Expand image Example

This example requires that you create the following variables.

Name | DataType
TempFile | File
NewStream | InStream
ToFileName | File
CopyCode image Copy Code
TempFile.CREATEINSTREAM(NewStream);
ToFileName := 'SampleFile.txt';
DOWNLOADFROMSTREAM(NewStream,’ Export’,'', ’ All Files (*.*)|*.*’,ToFileName)

Expand image See Also

Tasks

Walkthrough: Transferring a File from Microsoft Dynamics NAV Server to the Client

Reference

File Data Type


ERASE Function (File)

ERASE Function (File)
See Also
CollapseAll image

Use this function to erase a file.

[Ok :=] File.ERASE(Name)

Parameters

Name

Type: text or code

The name of the file you want to erase, including the path. When you enter the path, keep in mind these shortcuts:

  • You can omit the drive designation, if the file is located on the current drive.

  • You can omit the full path, if the file is located in the current directory.

  • You can enter only the subdirectory name, if the file is located in a subdirectory of the current directory

Expand image Property Value/Return Value

Type: Boolean

This optional return value shows whether the file was erased.

true if the file was erased; otherwise, false.

Expand image Remarks

If you do not use the return value, and the file cannot be erased, a run-time error will occur. If you do include the return value in your code, it is assumed that you will handle any errors yourself.

Expand image See Also

Reference

File Data Type


EXISTS Function (File)

EXISTS Function (File)
See Also
CollapseAll image

Use this function to determine if a file exists.

[Ok :=] File.EXISTS(Name)

Parameters

Name

Type: text or code

The name of the file you want to check, including the path. When you enter the path, keep in mind these shortcuts:

  • You can omit the drive designation, if the file is located on the current drive.

  • You can omit the full path, if the file is located in the current directory.

  • You can enter only the subdirectory name, if the file is located in a subdirectory of the current directory.

Expand image Property Value/Return Value

Type: Boolean

This return value shows whether the file exists.

true if the file exists; otherwise, false.

Expand image See Also

Reference

File Data Type


GETSTAMP Function (File)

GETSTAMP Function (File)
See Also
CollapseAll image

Use this function to find out exactly when a file was last written to (return a timestamp).

[Ok :=] File.GETSTAMP(Name, Date [, Time])

Parameters

Name

Type: code or text

The name of the file, including the path. When you enter the path, keep in mind these shortcuts:

  • You can omit the drive designation, if the file is located on the current drive.

  • You can omit the full path, if the file is located in the current directory.

  • You can enter only the subdirectory name, if the file is located in a subdirectory of the current directory.

Date

Type: date

The date that the file was last written to.

Time

Type: time

(Optional) The time that the file was last written to.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, a run-time error occurs when the file cannot be found. When you include the return value, you must handle any errors. The return value can have these values:

true if the file exists; otherwise, false.

Expand image See Also

Reference

File Data Type


LEN Function (File)

LEN Function (File)
See Also
CollapseAll image

Use this function to return the length of an ASCII or binary file.

Length := File.LEN

Parameters

File

Type: file

Use this variable to refer to the file.

Expand image Property Value/Return Value

Type: integer

This shows the length of the file in bytes.

Expand image Remarks

This function is often used with POS Function (File) and SEEK Function (File).

Expand image See Also

Reference

File Data Type


NAME Function (File)

NAME Function (File)
See Also
CollapseAll image

Use this function to return the name of an ASCII or binary file.

Name := File.NAME

Parameters

File

Type: file

Use this variable to refer the file.

Expand image Property Value/Return Value

Type: text or code

This string contains the name of the file, including its path.

Expand image Remarks

You must use the OPEN Function (File) to open the file before you can use this function.

Expand image See Also

Reference

File Data Type


OPEN Function (File)

OPEN Function (File)
See Also Example
CollapseAll image

Opens an ASCII or binary file. This function does not create the file if it does not exist.

[Ok := ] File.OPEN(Filename)

Parameters

File

Type: File

Specifies the file.

Filename

Type: Text

Specifies the name and path of the file that you want to open.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether the file was opened. If you omit this optional return value and if the file cannot be found, then a run-time error occurs.

true if the file was opened; otherwise, false.

Expand image Differences Between the Classic Client and RoleTailored Client

If you are running the RoleTailored client and you call OPEN on a file variable that refers to an open file, then the function does not automatically close the existing file and open the new file. You must explicitly call the CLOSE Function (File) to close the existing file. If you call OPEN on a file that is already open, then a run-time error occurs.

If you are running the Classic client and you call OPEN on a file variable that refers to an open file, then the function closes the existing file and opens the new file. A run-time error does not occur.

Expand image Example

This example shows how to open an .xml file for reading in ASCII mode. To use this example, you must create the simple.xml file at C:\temp and create the following variable.

Variable | Data type
TestFile | File
CopyCode image Copy Code
TestFile.TEXTMODE(TRUE);
TestFile.WRITEMODE(FALSE);
TestFile.OPEN('C:\temp\simple.xml');

Expand image See Also

Reference

File Data Type


POS Function (File)

POS Function (File)
See Also
CollapseAll image

Use this function to return the current position of the file pointer in an ASCII or binary file.

Position := File.POS

Parameters

File

Type: file

Use this variable to refer to the file.

Expand image Property Value/Return Value

Type: integer

This show the current position of the file pointer in bytes.

Expand image Remarks

This function is often used with LEN Function (File) and SEEK Function (File).

Expand image See Also

Reference

File Data Type


QUERYREPLACE Function (File)

QUERYREPLACE Function (File)
See Also
CollapseAll image

If a file already exists, use this function to determine whether to query a user before overwriting the file. This function can also be used to determine the settings for this option on a specific file.

[IsQueryreplace :=] File.QUERYREPLACE([SetQueryreplace])

Parameters

File

Use this variable to refer to the file.

SetQueryreplace

Type: Boolean

Sets the options for the file.

true, if the user must be queried before the file is replaced; otherwise, false.

Expand image Property Value/Return Value

Type: Boolean

The current setting of the option for the file.

true, if the user must be queried before the file is replaced; otherwise, false.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Reference

File Data Type


READ Function (File)

READ Function (File)
See Also
CollapseAll image

Use this function to read from an ASCII or binary file.

[Read :=] File.READ(Variable)

Parameters

File

Type: file

Use this variable to refer to the file.

Variable

Type: any

The destination variable. Must be the maximum length for the variable type.

Note Note

In previous versions of Microsoft Dynamics NAV, the Variable parameter did not have to be the maximum length. The READ function could read partial data. In Microsoft Dynamics NAV 2009, it is not supported to read fewer than the maximum bytes.

Expand image Property Value/Return Value

Type: integer

This optional return value shows the number of bytes read.

Expand image Remarks

If TEXTMODE Function (File) is set to true, a line of text from the file is read, evaluated, and the variable is set equal to the result.

If TEXTMODE is set to false, the number of bytes to read is determined by the size of the variable.

Expand image See Also

Reference

File Data Type


RENAME Function (File)

RENAME Function (File)
See Also
CollapseAll image

Use this function to rename an ASCII or binary file.

[Ok :=] File.RENAME(OldName, NewName)

Parameters

OldName

Type: text or code.

The current name of the file you want to change, including its path. When you enter the path, keep in mind these shortcuts:

  • You can omit the drive designation, if the file is located on the current drive.

  • You can omit the full path, if the file is located in the current directory.

  • You can enter only the subdirectory name, if the file is located in a subdirectory of the current directory.

NewName

Type: text or code

The new name you want to assign to the file, including its path. When you enter the path, keep in mind these shortcuts:

  • You can omit the drive designation, if the file is located on the current drive.

  • You can omit the full path, if the file is located in the current directory.

  • You can enter only the subdirectory name, if the file is located in a subdirectory of the current directory.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, a run-time error occurs when the file cannot be found. When you include the return value, it is assumed you will handle any errors.

true if the file was renamed; otherwise, false.

Expand image Remarks

Typically the return value is false if the file does not exist, or if the file is a system or hidden file.

Expand image See Also

Reference

File Data Type


SEEK Function (File)

SEEK Function (File)
See Also
CollapseAll image

Use this function to set a file pointer to a new position in an ASCII or binary file.

File.SEEK(Position)

Parameters

File

Type: file

Use this variable to refer to the file.

Position

Type: integer

The position at which you want to place the pointer.

Expand image Remarks

This function is often used with POS Function (File) and LEN Function (File).

Expand image See Also

Reference

File Data Type


SETSTAMP Function (File)

SETSTAMP Function (File)
See Also
CollapseAll image

Use this function to set a timestamp for a file.

[Ok :=] File.SETSTAMP(Name, Date [, Time])

Parameters

Name

Type: text or code.

The name of the file, including its path. When you enter the path, keep in mind these shortcuts:

  • You can omit the drive designation, if the file is located on the current drive.

  • You can omit the full path, if the file is located in the current directory.

  • You can enter only the subdirectory name, if the file is located in a subdirectory of the current directory.

Date

Type: date

The date you want stamped on the file.

Time

Type: time

The time you want stamped on the file.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, a run-time error occurs if the file cannot be found. When you include the return value, you must handle any errors.

true if the timestamp was set; otherwise false.

Expand image See Also

Reference

File Data Type


TEXTMODE Function (File)

TEXTMODE Function (File)
See Also
CollapseAll image

Sets whether a file should be opened as an ASCII file or a binary file. Also determines what the current setting of this option is for a file.

[IsTextmode := File.TEXTMODE([SetTextmode])

Parameters

File

Type: File

Specifies the file

SetTextmode

Type: Boolean

Specifies the mode in which the file will be opened when File.OPEN is called.

If SetTextmode is true, the file will be opened as an ASCII file. If SetTextmode is false, the file will be opened as a binary file.

Expand image Property Value/Return Value

Type: Boolean

The current setting of this option for the file.

true if the file will be opened as an ASCII file; otherwise, false if the file will be opened as a binary file.

Expand image Remarks

This function should be used before File.OPEN is used to open the file. In Microsoft Dynamics NAV 2009, if you use this function on a file that is already open, an error will occur.

Expand image See Also

Reference

File Data Type


TRUNC Function (File)

TRUNC Function (File)
See Also
CollapseAll image

Use this function to truncate an ASCII or binary file to the current position of the file pointer.

File.TRUNC

Parameters

File

Type: file

Use this variable to refer to the file.

Expand image Remarks

Typically, you use this function with SEEK Function (File). Use File.SEEK to position the pointer in the file and then use File.TRUNC to truncate the file at that point.

Expand image See Also

Reference

File Data Type


UPLOAD Function (File)

UPLOAD Function (File)
See Also Example
CollapseAll image

Sends a file from a RoleTailored client to a Microsoft Dynamics NAV Service.

[Ok :=] UPLOAD(DialogTitle, FromFolder, FromFilter, FromFile, ToFile)

Parameters

DialogTitle

Type: Text

The title that you want to display on the dialog box.

FromFolder

Type: Text

The name of the folder that is displayed in the dialog box. This is the default value and the user can change it.

FromFilter

Type: Text

The type of file that is displayed in the dialog box. This is the default value and the user can change it.

FromFile

Type: Text

The name of the file that you want to upload to the Microsoft Dynamics NAV service.

ToFile

Type: Variant

The file name that is shown in the dialog box. This is the default value and the user can change it.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, a run-time error occurs if the file cannot be found. If you include a return value, it is assumed that you will handle any errors.

true if the file was uploaded; otherwise, false.

Expand image Remarks

In the new architecture the business logic is run on the middle-tier server and not on the client.

This means that in Microsoft Dynamics NAV, files are created on the Microsoft Dynamics NAV service and not locally on the client computer as is the case in the Classic client. When you write code for the application, you must therefore remember where the files are created.

UPLOAD Function (File) and UPLOADINTOSTREAM Function (File) are used to send a file from a RoleTailored client to a Microsoft Dynamics NAV service.

DOWNLOAD Function (File) and DOWNLOADFROMSTREAM Function (File) are used to send a file from a Microsoft Dynamics NAV service to a RoleTailored client.

Expand image Example

CopyCode image Copy Code
UPLOAD(‘Upload file’,’C:\’,’Text file(*.txt)|*.txt’,’Test.txt’,’Test’)

Expand image See Also

Reference

File Data Type


UPLOADINTOSTREAM Function (File)

UPLOADINTOSTREAM Function (File)
See Also Example
CollapseAll image

Sends a file from a RoleTailored client to the corresponding Microsoft Dynamics NAV Server.

[Ok :=] UPLOADINTOSTREAM(DialogTitle, FromFolder, FromFilter, FromFile, NVInStream)

Parameters

DialogTitle

Type: Text

The text displayed in the title bar of the Open dialog box.

FromFolder

Type: Text

The path to the folder that is displayed in the File Open dialog box. This is the default folder, but the user can browse to any available location.

FromFilter

Type: Text

The type of file that is displayed in the Open dialog box. This is the default value and the user can change it.

FromFile

Type: Text

The name of the file that is displayed in the Open dialog box. This is the default file name, which the user can change.

NVInStream

Type: Variant

The InStream used to send the file.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, a run-time error occurs if the record cannot be found. If you include a return value, it is assumed that you will handle any errors.

true if the file was uploaded; otherwise, false.

Expand image Remarks

The maximum size of the file to be uploaded is specified by the MaxUploadSize setting in the CustomSettings.config file. The setting is specified in megabytes. For more information, see Configuring Microsoft Dynamics NAV Server.

In the new architecture the business logic is run on the Microsoft Dynamics NAV server and not on the client. This means that in Microsoft Dynamics NAV, files are created on the Microsoft Dynamics NAV server and not locally on the client computer as is the case with the Classic client. When you write code for Microsoft Dynamics NAV, you must therefore remember where the files are created.

Use UPLOAD Function (File) and UPLOADINTOSTREAM Function (File) to send a file from a RoleTailored client to Microsoft Dynamics NAV server.

Use DOWNLOAD Function (File) and DOWNLOADFROMSTREAM Function (File) to send a file from a Microsoft Dynamics NAV server to a RoleTailored client.

We recommend that you use the functions in Codeunit 419, 3-Tier Automation Mgt., to upload and download files.

Expand image Example

This example requires that you create the following variables.

Name | DataType
FileName | Text
NVInStream | InStream
CopyCode image Copy Code
FileName := 'c:\SomeFile.txt';
UPLOADINTOSTREAM(‘Import’,'',’ All Files (*.*)|*.*’,FileName,NVInStream);

Expand image See Also

Tasks

Walkthrough: Uploading a File from a Client to Microsoft Dynamics NAV Server

Reference

File Data Type


WRITE Function (File)

WRITE Function (File)
See Also
CollapseAll image

Use this function to write to an ASCII or binary file.

File.WRITE(Value)

Parameters

File

Type: file

Use this variable to refer to the file.

Value

Type: all simple, and records

The information you want to write to the file.

Expand image Remarks

If TEXTMODE Function (File) is set to true and Value is an integer, the integer is written as text, followed by a new line character.

If Value is a record, each field is separated by a tab character.

If TEXTMODE Function (File) is false and Value is an integer, an integer is written that is four bytes long.

Expand image See Also

Reference

File Data Type
TEXTMODE Function (File)


WRITEMODE Function (File)

WRITEMODE Function (File)
See Also
CollapseAll image

Use this function before you use OPEN Function (File) to set or test whether you can write to a file in later calls.

[IsWritemode :=] File.WRITEMODE([SetWritemode])

Parameters

File

Use this variable to refer to the file.

SetWritemode

Type: Boolean

This variable is used to set the mode that the file will be opened in when File.OPEN is called.

If true, the file is opened for reading and writing; otherwise, if false, the file is only opened for reading.

Expand image Property Value/Return Value

Type: Boolean

The current setting of this option for the file.

true you can read from and write to the file; false you can only read from the file.

Expand image Remarks

This function should be used before OPEN Function (File) is used to open the file.

Expand image See Also

Reference

File Data Type


Form Data Type

Form Data Type

Variables of this complex data type store forms. Forms contain simpler elements called controls. Controls are used to display information to the user or to receive information from the user.

Expand image See Also

Reference

ACTIVATE Function (Control)
ACTIVE Function (Form)
CAPTION Function (Form)
CLOSE Function (Form, Table)
EDITABLE Function (Control, Form)
FORM Function (Form)
FORM.RUN Function (Form)
FORM.RUNMODAL Function (Form)
GETRECORD Function (Form)
HEIGHT Function (Control, Form)
LOGHEIGHT Function (Form)
LOGWIDTH Function (Form)
LOOKUPMODE Function (Form)
MAXIMIZEDONOPEN Function (Form)
MINIMIZEDONOPEN Function (Form)
OBJECTID Function (Form)
RUN Function (Form)
RUNMODAL Function (Form)
SAVERECORD Function (Form)
SETRECORD Function (Form)
SETSELECTIONFILTER Function (Form)
SETTABLEVIEW Function (Dataport, Form, Report, XMLport)
UPDATE Function (Form)
UPDATECONTROLS Function (Form)
UPDATEEDITABLE Function (Control, Form)
URL Function (Form)
VISIBLE Function (Control, Form)
WIDTH Function (Control, Form)
XPOS Function (Control, Form)
YPOS Function (Control, Form)


ACTIVE Function (Form)

ACTIVE Function (Form)
See Also
CollapseAll image

Checks whether the current form is active or inactive.

IsActive := Form.ACTIVE

Expand image Property Value/Return Value

Type: Boolean

true if the form is active; otherwise, false.

Expand image See Also

Reference

Form Data Type


CAPTION Function (Form)

CAPTION Function (Form)
See Also Example
CollapseAll image

Returns the current caption of an object as a string and sets a new caption for the object.

[CurrCaption :=] Form.CAPTION([NewCaption])

Parameters

NewCaption

Type: Text or code

The new caption for the object.

Expand image Property Value/Return Value

Type: Text or code

The current caption, as a string.

Expand image Remarks

CAPTION returns the current caption or sets the caption of an object. CAPTION first looks for a CaptionML Property. If it finds one, it returns the caption portion of the CaptionML property. If it does not find one, it looks for a Caption Property. If that also fails, it will use the Name Property. This means that CAPTION includes multilanguage functionality.

When CAPTION is used to set a new caption for an object, this new caption is not stored with the object. It is only effective for the instance of the object where it is set.

For tables and fields in tables, you must use the TABLECAPTION Function (Record) or the FIELDCAPTION Function (Record).

Expand image Example

This example shows how to use the CAPTION function. This example assumes that the current form is form 42, Sales Order, and the CaptionML property of this form is ENU=Sales Order. This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
OriginalCaption | Text | 1024
NewCaption | Text | 1024
CaptionString | Text | 1024
Text Constant | ENU Value
Text000 | The original caption was %1.
Text001 | The new caption is %1.
CopyCode image Copy Code
OriginalCaption := CurrForm.CAPTION;
MESSAGE(Text000, OriginalCaption);
CaptionString := ' Some New Caption';
CurrForm.CAPTION(CaptionString);
NewCaption := CurrForm.CAPTION;
MESSAGE(Text001, NewCaption);

The message windows could display the following:

The original caption was Sales Order.

The new caption is Some New Caption.

Expand image See Also

Reference

Form Data Type

Concepts

Working with Multilanguage Functionality


CLOSE Function (Form, Table)

CLOSE Function (Form, Table)
See Also
CollapseAll image

Closes the current form or table.

Form.CLOSE

Expand image See Also

Reference

Form Data Type


FORM Function (Form)

FORM Function (Form)
See Also Example
CollapseAll image

Accesses a form that is a subform of the current form. This a form that is defined in the SubFormID Property of a subform control.

Subform := Form.FORM

Expand image Property Value/Return Value

Type: Form

Expand image Example

This example shows how to use the FORM function to execute a function that is a local function of a form used as a subform on the current form.
CopyCode image Copy Code
CurrForm.NameOfSubformControl.FORM.LocalFunctionToExecute;

Expand image See Also

Reference

Form Data Type


FORM.RUN Function (Form)

FORM.RUN Function (Form)
See Also Example
CollapseAll image

Creates and launches a form object, which you specify. If, at design time, you do not know the specific form that you want to run, use this function or the FORM.RUNMODAL Function (Form).

FORM.RUN(Number [, Record] [, Field])

Parameters

Number

Type: Integer

A number that identifies a form object. If you enter zero (0), the default lookup window for the current form is displayed. You can use the Symbols option on the View menu to choose from a list.

If the form that you specify does not exist, a run-time error occurs.

Record

Type: Record

The Form.RUN function shows, by default, the record last displayed on the form. For each object, information about the most recently shown record and the attached key and filters is stored.

Use this optional parameter to select a specific record to display on the form. The record must be of the same type as the table attached to the window. When the record is displayed, the key and filters attached to the record are used.

Field

Type: Field

Use this optional parameter to select a specific field on which focus will be placed.

Expand image Remarks

When you want to close the form, use CurrForm.CLOSE. CurrForm is a predefined system variable.

For more information about system-defined variables, see System-Defined Variables.

Note Important

If you have code that calls the FORM.RUN function and you run this code on the NAV Server, then the code is translated to call the PAGE.RUN Function instead.

Expand image Example

This example shows how to run form 4711.
CopyCode image Copy Code
FORM.RUN(4711);

Expand image See Also

Reference

Form Data Type


FORM.RUNMODAL Function (Form)

FORM.RUNMODAL Function (Form)
See Also Example
CollapseAll image

Creates, runs, and closes a form object that you specify. The form is run modally. When a form is run modally, no input (keyboard or mouse click) can occur except to objects on the modal form. If, at design time, you do not know the specific form that you want to run, use this function or the FORM.RUN Function (Form). If you do know the specific form that you want to run, you can use the RUN Function (Form) or RUNMODAL Function (Form) to specify a variable.

[Action :=] Form.RUNMODAL(Number [, Record] [, Field])

Parameters

Number

Type: Integer

A number that identifies a form object. If you enter zero (0), the default lookup window for the current form is displayed. You can use the Symbols option on the View menu to choose from a list.

If the form you specify does not exist, a run-time error occurs.

Record

Type: Record

This function shows, by default, the record last displayed on the form. For each object, information about the most recently shown record and the attached key and filters is stored.

Use this optional parameter to select a specific record to display on the form. The record must be of the same type as the table attached to the form. When the record is displayed, the key and filters attached to the record are used.

Field

Type: Field

Use this optional parameter to select a specific field on which focus will be placed.

Expand image Property Value/Return Value

Type: Code

Specifies what action the user took. The following table shows the possible return values.

Return value | Description
OK | The user selected OK to exit the window
Cancel | The user selected Cancel to exit the window
LookupOK | The user selected OK on a lookup window
LookupCancel | The user selected Cancel on a lookup window
Yes | The user selected Yes
No | The user selected No
Close | The user selected Close, ESC, or closed the window using the title bar
FormHelp | The user selected Help
RunObject | The user selected an option that ran another object
RunSystem | The user selected an option that ran an external program

Expand image Remarks

If you have code that calls the FORM.RUNMODAL function and you run this code on the NAV Server, then the code is translated to call the PAGE.RUNMODAL Function instead.

Expand image Example

This example shows how to use the FORM.RUNMODAL function to run form 4711.
CopyCode image Copy Code
IF FORM.RUNMODAL(4711, SomeRecord, ...) = Action::LookupOK THEN...

Expand image See Also

Reference

Form Data Type


GETRECORD Function (Form)

GETRECORD Function (Form)
See Also
CollapseAll image

Retrieves the current record shown on the form.

Form.GETRECORD(Record)

Parameters

Form

Type: Form

Record

Type: Record

The retrieved record.

Expand image See Also

Reference

Form Data Type


LOGHEIGHT Function (Form)

LOGHEIGHT Function (Form)
See Also
CollapseAll image

Returns the current setting of the LogHeight Property of a form and sets this property to a new value.

[CurrLogHeight :=] Form.LOGHEIGHT([NewLogHeight])

Parameters

NewLogHeight

Type: Integer

The new setting of the LogHeight Property.

Expand image Property Value/Return Value

Type: Integer

The current setting of the LogHeight Property.

Expand image Remarks

The LOGHEIGHT function is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

Form Data Type


LOGWIDTH Function (Form)

LOGWIDTH Function (Form)
See Also
CollapseAll image

Returns the current setting of the LogWidth Property of a form and sets this property to a new value.

[CurrLogWidth :=] Form.LOGWIDTH([NewLogWidth])

Parameters

NewLogWidth

Type: Integer

The new setting of the LogWidth Property.

Expand image Property Value/Return Value

Type: Integer

The current setting of the LogWidth Property.

Expand image Remarks

The LOGWIDTH function is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

Form Data Type


LOOKUPMODE Function (Form)

LOOKUPMODE Function (Form)
See Also
CollapseAll image

Returns the current setting of the LookupMode Property of a form and sets this property to a new value.

[CurrLookupMode :=] Form.LOOKUPMODE([NewLookupMode])

Parameters

NewLookupMode

Type: Boolean

The new setting of the LookupMode Property.

Expand image Property Value/Return Value

Type: Boolean

The current setting of the LookupMode Property.

Expand image See Also

Reference

Form Data Type


MAXIMIZEDONOPEN Function (Form)

MAXIMIZEDONOPEN Function (Form)
See Also
CollapseAll image

Returns the current setting of the MaximizedOnOpen Property of a form and sets this property to a new value.

[CurrMaximized :=] Form.MAXIMIZEDONOPEN([NewMaximized])

Parameters

NewMaximized

Type: Boolean

The new setting of the MaximizedOnOpen Property.

Expand image Property Value/Return Value

Type: Boolean

The current setting of the MaximizedOnOpen Property.

Expand image See Also

Reference

Form Data Type


MINIMIZEDONOPEN Function (Form)

MINIMIZEDONOPEN Function (Form)
See Also
CollapseAll image

Returns the current setting of the MinimizedOnOpen Property of a form and sets this property to a new value.

[CurrMinimized :=] Form.MINIMIZEDONOPEN([NewMinimized])

Parameters

NewMinimized

Type: Boolean

The new setting of the MinimizedOnOpen Property.

Expand image Property Value/Return Value

Type: Boolean

The current setting of the MinimizedOnOpen Property.

Expand image See Also

Reference

Form Data Type


OBJECTID Function (Form)

OBJECTID Function (Form)
See Also
CollapseAll image

Returns a string in the "form xxx" format, where xxx is the name or number of the application object.

String := Form.OBJECTID([UseNames])

Parameters

Form

Type: Form

UseNames

Type: Boolean

The UseNames parameter is optional. If it is set to true (default value) or if it is empty, the returned string contains references to field names in the table with which the record is associated. If the parameter is set to false, field numbers are used instead.

Expand image Property Value/Return Value

Type: Text or code

Expand image See Also

Reference

Form Data Type


RUN Function (Form)

RUN Function (Form)
See Also Example
CollapseAll image

Creates and launches a form that you specify. You can use the CLEAR Function to remove the form. Use this function or the RUNMODAL Function (Form) function if you know at design time the exact form you want to run. Otherwise, use the FORM.RUNMODAL Function (Form) or the FORM.RUN Function (Form).

Form.RUN

Parameters

Form

Type: Form

After you define this variable, you can run the following form functions:

  • SETTABLEVIEW

  • SETRECORD

  • GETRECORD

  • RUN

  • RUNMODAL

The variable is automatically cleared after this function runs.

If the form you specify does not exist, a compile error occurs.

Expand image Remarks

After you define the variable Form1, you can use it before you run the form. If you use the RUNMODAL (form) function, you can use the variable before and after you run the form.

Expand image Example

This example shows how to use the RUN function. Assume that the variable Form1 has been defined as Form 1.
CopyCode image Copy Code
Form1.XXX; // any user-defined function
Form1.SETTABLEVIEW(MyRecord);
Form1.SETRECORD(MyRecord);
Form1.RUN;

Expand image See Also

Reference

Form Data Type


RUNMODAL Function (Form)

RUNMODAL Function (Form)
See Also Example
CollapseAll image

Creates, runs, and closes a form object that you specify. When a form is run modally, no input (keyboard or mouse click) can occur except to objects on the modal form. If, at design time, you know the specific form that you want to run, use this function or the RUN Function (Form). If you do not know the specific form that you want to run, you can use the FORM.RUNMODAL Function (Form) or the FORM.RUN Function (Form).

[Action :=] Form.RUNMODAL

Parameters

Form

Type: Variable

After you define this variable, you can run the following form functions:

  • SETTABLEVIEW

  • SETRECORD

  • GETRECORD

  • RUN

  • RUNMODAL

Unlike the Form.RUN function, the variable is not automatically cleared after this function runs.

If the form you specify does not exist, a compilation error occurs.

Expand image Property Value/Return Value

Type: Code

Specifies what action the user took. The return value is optional. The following table shows the possible return values.

Return value | Description
OK | The user selected OK to exit the window
Cancel | The user selected Cancel to exit the window
LookupOK | The user selected OK on a lookup window
LookupCancel | The user selected Cancel on a lookup window
Yes | The user selected Yes
No | The user selected No
Close | The user selected Close, ESC, or closed the window using the title bar
FormHelp | The user selected Help
RunObject | The user selected an option that ran another object
RunSystem | The user selected an option that ran an external program

Expand image Remarks

After you define the variable Form1, you can use it before and after you run the form. If you use the Form.RUN function, you can only use the variable before you run the form.

Expand image Example

This example shows how to use the RUNMODAL function. Assume that the variable Form1 has been defined as Form 1.
CopyCode image Copy Code
CLEAR(Form1);
Form1.XXX; // any user-defined function
Form1.SETTABLEVIEW(MyRecord);
Form1.SETRECORD(MyRecord);
IF Form1.RUNMODAL = Action::LookupOK THEN Form1.GETRECORD(MyRecord)...

This code example includes the CLEAR Function to verify that the variable has been cleared.

Expand image See Also

Reference

Form Data Type


SAVERECORD Function (Form)

SAVERECORD Function (Form)
See Also
CollapseAll image

Saves the current record shown on the form.

CurrForm.SAVERECORD

Expand image Remarks

This function saves the current record to the table.

This function is similar to the UPDATE Function (Form).

Expand image See Also

Reference

Form Data Type


SETRECORD Function (Form)

SETRECORD Function (Form)
See Also
CollapseAll image

Selects the current record shown on the form.

Form.SETRECORD(Record)

Parameters

Form

Type: Form

Record

Type: Record

The record that you want to select as the current record.

Expand image Remarks

You can use this function to select a record to display when the user opens the form. If you use this function for this purpose, it will override the SourceTableRecord Property "Saved" setting. The current record will not be saved in the setup file.

Expand image See Also

Reference

Form Data Type


SETSELECTIONFILTER Function (Form)

SETSELECTIONFILTER Function (Form)
See Also
CollapseAll image

Notes the records that the user has selected on the form, marks those records in the table specified, and sets the filter to "marked only".

CurrForm.SETSELECTIONFILTER(Record)

Parameters

Record

Type: Record

A specific record or records.

Expand image Remarks

If either all or no records are selected, marks will not be used.

If one or more records are selected on the form, then SetSelectionFilter does the following:

  • Copies the current key from the form source table to the destination record

  • Copies the current sort order from the table to the destination record

  • Copies the current filters that are set in all filter groups

  • Copies the current filter group

  • Marks the selected records and sets the "marked only" filter

If no record is selected on the form, then SetSelectionFilter does the following:

  • Sets the current filter group to 0 on the destination record

  • Adds filters on the primary key fields that point to the current record of the form

Expand image See Also

Reference

Form Data Type


UPDATE Function (Form)

UPDATE Function (Form)
See Also
CollapseAll image

Saves the current record and then updates the controls in the form. If you set the SaveRecord parameter to false, this function will not save the record before the the form is updated.

CurrForm.UPDATE[(SaveRecord)]

Parameters

SaveRecord

Type: Boolean

Set this parameter to true if you want to save the current record. Set this parameter to false if you want to update without saving the current record.

Expand image See Also

Reference

SAVERECORD Function (Form)
Form Data Type


UPDATECONTROLS Function (Form)

UPDATECONTROLS Function (Form)
See Also
CollapseAll image

Reloads the captions of all controls on the current form. This is necessary when the user changes the CaptionClass of a control after the form has been loaded.

CurrForm.UPDATECONTROLS

Expand image See Also

Reference

Form Data Type


URL Function (Form)

URL Function (Form)
See Also
CollapseAll image

Returns a string that contains the full URL to a form.

String := Form.URL([UseNames])

Parameters

Form

Type: Form

UseNames

Type: Boolean

The UseNames parameter is optional. If it is set to true (default value) or if it is empty, the returned string contains references to field names in the table with which the record is associated. If the parameter is set to false, field numbers are used instead.

Expand image Property Value/Return Value

Type: text or code

Expand image Remarks

This function is equivalent to the functionality in the menu item Copy Link.

For examples about how to format URLs, see Composing URLs.

Expand image See Also

Reference

Form Data Type


GUID Data Type

GUID Data Type

Assigns a unique identifying number to any database object. The GUID data type is a 16 byte binary data type. This data type is used for the global identification of objects, programs, records, and so on. The important property of a GUID is that each value is globally unique. The value is generated by an algorithm, developed by Microsoft, which assures this uniqueness.

The GUID is a 16-byte binary data type that can be logically grouped into the following subgroups:

4byte-2byte-2byte-2byte-6byte.

The standard textual representation is {12345678-1234-1234-1234-1234567890AB}.

The virtual table OLE Control (2000000042) does not use the GUID data type. It uses a textual representation of the GUID in a text field instead. It is easier to make operations and references to this text field using the GUID data type than it is using the textual representation. The GUID data type is compatible with the existing textual representation.

The GUID data type is useful when you want to uniquely identify some data, so that it can be exchanged with external applications. For example, if you want to transfer an item catalog to an external application, you add a GUID field to the record in the table and use this as the primary reference when you communicate with the external application.

Expand image Compatibility

You can assign and compare the TEXT data type and the GUID data type. Assigning a GUID to a TEXT can be done as follows:

CopyCode image Copy Code
MyTableRec.MyGuid  :=  MyTableRec.MyText;

Expand image Useful C/AL Functions and Properties

The following C/AL functions can be used with the GUID data type:

CopyCode image Copy Code
Guid:=CREATEGUID();

This function creates a new unique GUID value. The value can then be assigned to a field of the GUID data type or of the TEXT data type.

CopyCode image Copy Code
Ok:=ISNULLGUID(Guid);

This function is a convenient way to check if a value has already been assigned to a GUID. A NULL GUID (consisting only of zeroes) is valid, but should never be used for reference purposes.

CopyCode image Copy Code
CLEAR(Guid);

The standard CLEAR function can also be used on the GUID data type. It nullifies the GUID.

CopyCode image Copy Code
AutoSplitKey

A NULL GUID is valid but is not useful in a table. Therefore, the AutoSplitKey property is implemented for the GUID data type when it is used in a form. When GUID is selected as a primary key, AutoSplitKey is enabled for the form, and the GUID value remains NULL. When you create a new record, a valid GUID is created and assigned automatically.

The CREATEGUID Function (GUID) and ISNULLGUID Function (GUID) functions are available in the C/AL Symbol Menu under SYSTEM, Variables.

CREATEGUID takes no arguments and returns a valid 16-byte GUID value. If the result is assigned to a TEXT variable or field, the value is converted to a string and follows the syntax explained earlier. The algorithm that generates the new GUID value uses Microsoft's CoCreateGuid function.

ISNULLGUID takes a GUID value as a required argument and returns TRUE/FALSE depending on whether the GUID value is NULL. This function does not accept a TEXT value as an argument.

CLEAR is the standard CLEAR function and takes one required argument. It nullifies the GUID value in the same way as it resets any other value.

AutoSplitKey is a property, not a function and can be applied to forms. If you have defined a GUID field as part of the primary key, the AutoSplitKey property automatically generates a new valid GUID value. When a new record is created and the GUID field is left as NULL, the AutoSplitKey property ensures that a valid GUID value is automatically inserted into the field. If you then enter a NULL GUID into this record, for example, by using the CLEAR function, this new NULL GUID value is not automatically replaced by the AutoSplitKey property. The AutoSplitKey property only applies to new records.

Expand image Format

The GUID value can also be represented as text. You can use the standard C/AL functions FORMAT and EVALUATE to convert from GUID values to TEXT values. If you do not use the correct format when you edit a GUID value in its textual format, the following error message is displayed:

Invalid Format of GUID string. The correct format of the GUID string is {CDEF7890-ABCD-1234-ABCD-1234567890AB} where 0-9, A-F symbolizes hexadecimal digits.

Expand image See Also

Reference

CREATEGUID Function (GUID)
ISNULLGUID Function (GUID)


CREATEGUID Function (GUID)

CREATEGUID Function (GUID)
See Also
CollapseAll image

Creates a new unique GUID. The value can then be assigned to a GUID data type or a text data type. Use the text data type if you want to compare the GUID to another text string.

Guid := CREATEGUID;

Expand image Property Value/Return Value

Type: GUID

Expand image See Also

Reference

GUID Data Type


ISNULLGUID Function (GUID)

ISNULLGUID Function (GUID)
See Also
CollapseAll image

Indicates whether a value has been assigned to a GUID. A null GUID that consists only of zeros is valid but must never be used for reference purposes.

Ok := ISNULLGUID(Guid);

Parameters

Guid

The GUID that you want to check whether it is null.

Expand image Property Value/Return Value

Type: Boolean

true if a value has been assigned to the GUID; otherwise, false.

Expand image See Also

Reference

GUID Data Type


InStream and OutStream Data Types

InStream and OutStream Data Types

Reads from or writes to files and BLOBs.

Expand image Remarks

The InStream (input stream) and OutStream (output stream) data types are generic stream objects that you can use to read from or write to files and BLOBs. In addition, the InStream and OutStream data types enable data to be read from and sent to Automation Data Type objects and OCX Data Type objects. The Microsoft XML DOM can read from an InStream object and write to an OutStream object.

You can define the internal structure of a stream as a flat stream of bytes. You can assign one stream to another. Reading from and writing to a stream occurs sequentially.

You can create a stream object by using the following functions:

  • CREATEINSTREAM Function (BLOB)

  • CREATEOUTSTREAM Function (BLOB)

  • CREATEINSTREAM Function (File)

  • CREATEOUTSTREAM Function (File)

You can use InStream in the following ways:

  • COPYSTREAM Function (InStream, OutStream)

  • InStream.READ Function

  • InStream.EOS Function

  • InStream.READTEXT Function

You can use OutStream in the following ways:

  • COPYSTREAM Function (InStream, OutStream)

  • OutStream.WRITE Function

  • OutStream.WRITETEXT Function

Expand image See Also

Reference

Code Example for Streams


InStream

InStream

This section contains the following topics:

  • COPYSTREAM Function (InStream, OutStream)

  • InStream.EOS Function

  • InStream.READ Function

  • InStream.READTEXT Function


COPYSTREAM Function (InStream, OutStream)

COPYSTREAM Function (InStream, OutStream)
See Also Example
CollapseAll image

Copies the information contained in an InStream to an OutStream.

[Ok :=] COPYSTREAM(OutStream, InStream)

Parameters

OutStream

Type: OutStream

The OutStream object to which you will copy the information; the destination stream.

InStream

Type: InStream

The InStream object from which you want to copy; the source stream.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether the data was copied.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType
F1 | File
F2 | File
InS | InStream
OutS | OutStream
CopyCode image Copy Code
F1.OPEN('c:\Test.txt');
F1.CREATEINSTREAM(InS);
F2.CREATE('c:\CopyTest.txt');
F2.CREATEOUTSTREAM(OutS);
COPYSTREAM(OutS,InS);
F1.CLOSE();
F2.CLOSE();

Expand image See Also

Reference

InStream and OutStream Data Types


InStream.EOS Function

InStream.EOS Function

Indicates whether an input stream has reached End of Stream (EOS).

IsEOS := InStream.EOS

Expand image Property Value/Return Value

Type: Boolean

Yes if the stream has reached End of Stream; otherwise, No.

Expand image Remarks

If you are reading data from an external component, EOS can return FALSE even though no more data is available. This may happen if you have not called READ first.

Expand image See Also

Reference

Code Example for Streams
InStream.READ Function
InStream.READTEXT Function
InStream and OutStream Data Types


InStream.READ Function

InStream.READ Function
See Also Example
CollapseAll image

Reads a specified number of bytes from an InStream object. Data is read in binary format.

[Read := ] InStream.Read(Variable[, Length])

Parameters

Variable

Describes the variable that will receive the data that is read.

Length

Describes the number of characters to be read. If you do not specify Length, the size of the variable is used. In the case of data types other than string, code, and binary, if you specify a length that differs from the size of the variable, an error message appears.

Expand image Property Value/Return Value

Type: integer

The return value is the number of characters that were read.

Expand image Remarks

If the optional return value (READ) is not present and the data being read is less than the length requested to be read, an error message will appear.

If the return value is present, you must verify the validity of the data that has been read.

Expand image Example

CopyCode image Copy Code
recBinaries.FIND('-');
recBinaries.CALCFIELDS(Data);
recBinaries.CREATEINSTREAM(InStream);
InStream.READ(Title);
InStream.READ(Name);
InStream.READ(Surname);
InStream.READ(AltStartDate);

Expand image See Also

Reference

Code Example for Streams
InStream.EOS Function
InStream.READTEXT Function
OutStream.WRITE Function
InStream and OutStream Data Types


InStream.READTEXT Function

InStream.READTEXT Function
See Also Example
CollapseAll image

Reads text from an InStream object.

[Read := ] InStream.ReadText(Text[, Length])

Parameters

Text

Type: Text

The variable that receives the characters that were read

Length

Type: Integer

The number of characters to be read. If you do not specify this parameter, the maximum length of the string is used.

Expand image Property Value/Return Value

Type: Integer

The number of characters that were read.

Expand image Remarks

READTEXT reads the specified number of bytes, the maximum length of the string, or until the end of the line.

Data is read in text format.

If you do not use the optional return value and the data being read is less than the length requested to be read, an error message is displayed.

If you use the return value, you must verify the validity of the data that has been read.

Expand image Example

This example shows how to use the InStream.READTEXT function. This example requires that you create the following variables.

Variable name | DataType
FileTest | File
StreamInTest | InStream
Int | Integer
Txt | Text
CopyCode image Copy Code
FileTest.OPEN('c:\XMLDocs\NewTest.txt');
FileTest.CREATEINSTREAM(StreamInTest);
// Starting a loop
WHILE NOT (StreamInTest.EOS) DO BEGIN
  Int := StreamInTest.READTEXT(Txt,100);
  MESSAGE(Txt + '\Size: ' + FORMAT(Int));
END;
FileTest.CLOSE();

Expand image See Also

Reference

InStream and OutStream Data Types
Code Example for Streams
InStream.READ Function
InStream.EOS Function


OutStream

OutStream

This section contains the following topics:

  • COPYSTREAM Function (InStream, OutStream)

  • OutStream.WRITE Function

  • OutStream.WRITETEXT Function


OutStream.WRITE Function

OutStream.WRITE Function
See Also Example
CollapseAll image

Writes a specified number of bytes to the stream. Data is written in binary format.

[Written := ] OutStream.Write(Variable[, Length])

Parameters

Variable

Contains the data to be written

Length

The number of bytes to be written. In the case of data types other than string, code, and binary, if you specify a length that differs from the size of the variable, an error message is displayed.

Expand image Property Value/Return Value

Type: Integer

The number of bytes that were written.

Expand image Remarks

If the optional return value (Written) is not specified and it was not possible to write all the data, an error message is displayed.

If the return value is present, you must verify that all the data was streamed.

Expand image Example

CopyCode image Copy Code
recBinaries.FIND('-');
recBinaries.Data.CREATEOUTSTREAM(OutStream);
OutStream.WRITE('Secretary');
OutStream.WRITE('Alice');
OutStream.WRITE('Hart');
OutStream.WRITE(010696D);
recBinaries.MODIFY();

Expand image See Also

Reference

InStream and OutStream Data Types
Code Example for Streams
OutStream.WRITETEXT Function


OutStream.WRITETEXT Function

OutStream.WRITETEXT Function
See Also Example
CollapseAll image

Writes text to an OutStream object.

[Written := ] OutStream.WriteText([Text[, Length]])

Parameters

Text

The text to write. If you do not specify this, a carriage return and a line feed are written.

Length

The number of characters to be written.

Expand image Property Value/Return Value

Type: Integer

The number of characters that were written.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType
MyHTMLFile | File
TestOutStream | OutStream

This example also requires that the c:\TestFiles folder exists.
CopyCode image Copy Code
MyHTMLFile.CREATE('c:\TestFiles\main.html');
MyHTMLFile.CREATEOUTSTREAM(TestOutStream);
TestOutStream.WRITETEXT('<html>');
TestOutStream.WRITETEXT;
TestOutStream.WRITETEXT('<head>');
TestOutStream.WRITETEXT('<title>My Page</title>');
TestOutStream.WRITETEXT('</head>');
TestOutStream.WRITETEXT;
TestOutStream.WRITETEXT('<P>Hello world!</p>');
TestOutStream.WRITETEXT;
TestOutStream.WRITETEXT('</html>');
FileMyHTML.CLOSE;

Expand image See Also

Reference

InStream and OutStream Data Types
Code Example for Streams
OutStream.WRITE Function


Code Example for Streams

Code Example for Streams

The code examples in this topic demonstrate how you can read from and write to streams. These examples require the following variables.

Variable name | Data type | Subtype
recEmployee | Record | Employee
XMLDom | Automation | XMLDomDoc
StreamOutObj | OutStream |
StreamInObj | InStream |
Txt | Text |
Buffer | Text |
CreationDate | Date |

Expand image Writing Data to an OutStream

The following code example creates an OutStream to stream data out of a BLOB field for storage in an external object.

CopyCode image Copy Code
// Define the record number.
recEmployee."No." := '5555';
// Load the XML DOM, which will pass the OutStream to the
// external object.
XMLDom.load('SomeData.xml');
recEmployee.Picture.CREATEOUTSTREAM(StreamOutObj);
StreamOutObj.WRITE('Ver. 1.00');
// Write version.
StreamOutObj.WRITE('Company Ltd.');
// Write (c).
StreamOutObj.WRITE(TODAY);
// Write a DATE (today).
// The following information will be written as plain text.
StreamOutObj.WRITETEXT('Dear Customer,');
StreamOutObj.WRITETEXT();
// This inserts a carriage return and a new line.
StreamOutObj.WRITETEXT('We would like to thank you for your help.');
StreamOutObj.WRITETEXT();
StreamOutObj.WRITETEXT('We hope to see you soon!');
StreamOutObj.WRITETEXT();
XMLDom.save(StreamOutObj);
recEmployee.MODIFY();

Expand image Reading Data from an InStream

The following code creates an InStream to stream data into a BLOB field. This example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text000 | 'Version is: %1'
Text001 | 'Copyright %1'
Text002 | 'Creation Date: %1'
CopyCode image Copy Code
recEmployee.Picture.CREATEINSTREAM(StreamInObj);
// Read version.
StreamInObj.READ(Txt);
MESSAGE(Text000, Txt);
// Read (c).
StreamInObj.READ(Txt);
MESSAGE(Text001, Txt);
// Read date.
StreamInObj.READ(CreationDate);
MESSAGE(Text002, CreationDate);
StreamInObj.READTEXT(Buffer);
Message(Buffer);
StreamInObj.READTEXT(Buffer);
Message(Buffer);
StreamInObj.READTEXT(Buffer);
Message(Buffer);
XMLDom.load(StreamInObj);

Expand image See Also

Reference

InStream and OutStream Data Types


Key Groups

Key Groups

This section contains the following topics:

  • KEYGROUPDISABLE Function

  • KEYGROUPENABLE Function

  • KEYGROUPENABLED Function


KEYGROUPDISABLE Function

KEYGROUPDISABLE Function

Disables a key group.

[Ok :=] KEYGROUPDISABLE(GroupName)

Parameters

GroupName

Type: String

The name of the key group that you want to disable.

On the Classic client, if the GroupName parameter that you specify does not exist, then an error message is displayed and execution continues.

On the RoleTailored client, if the GroupName parameter that you specify does not exist, then no error message is displayed and false is returned.

Expand image Property Value/Return Value

Type: Boolean

This optional return value specifies whether the key group was disabled.

true if the key group was disabled; otherwise, false.

Expand image See Also

Reference

KEYGROUPENABLE Function
KEYGROUPENABLED Function


KEYGROUPENABLE Function

KEYGROUPENABLE Function

Enables a key group.

[Ok :=] KEYGROUPENABLE(GroupName)

Parameters

GroupName

Type: String

The name of the key group that you want to enable.

On the Classic client, if the GroupName parameter that you specify does not exist, then an error message is displayed and execution continues.

On the RoleTailored client, if the GroupName parameter that you specify does not exist, then no error message is displayed and false is returned.

Expand image Property Value/Return Value

Type: Boolean

This optional return value specifies whether the key group was enabled.

true if the key group was enabled; otherwise, false.

Expand image See Also

Reference

KEYGROUPDISABLE Function
KEYGROUPENABLED Function


KEYGROUPENABLED Function

KEYGROUPENABLED Function

Indicates whether a specific key group is enabled.

[Ok :=] KEYGROUPENABLED(GroupName)

Parameters

GroupName

Type: String

The name of the key group that is enabled.

On the Classic client, if the GroupName parameter that you specify does not exist, then an error message is displayed and execution continues.

On the RoleTailored client, if the GroupName parameter that you specify does not exist, then no error message is displayed and false is returned.

Expand image Property Value/Return Value

Type: Boolean

This optional return value specifies whether the key group is enabled.

true if the key group is enabled; otherwise, false.

Expand image See Also

Reference

KEYGROUPDISABLE Function
KEYGROUPENABLE Function


KeyRef Data Type

KeyRef Data Type

Identifies a key in a table and the fields in this key.

Expand image Remarks

This complex data type gives you access to the key and the fields it contains.

The keyref object can refer to any key in any table in the database.

Expand image See Also

Reference

ACTIVE Function (KeyRef)
FIELDCOUNT Function (KeyRef)
FIELDINDEX Function (KeyRef)
RECORD Function (KeyRef)


ACTIVE Function (KeyRef)

ACTIVE Function (KeyRef)
See Also
CollapseAll image

Indicates whether the key is enabled.

Ok := KeyRef.ACTIVE

Parameters

KeyRef

Type: keyref

The keyref that refers to a key.

Expand image Property Value/Return Value

Type: Boolean

true if the key is enabled; otherwise, false.

Expand image See Also

Reference

KeyRef Data Type


FIELDCOUNT Function (KeyRef)

FIELDCOUNT Function (KeyRef)
See Also
CollapseAll image

Returns the number of fields that have been defined in a key. Returns an error if no key is selected.

No := KeyRef.FIELDCOUNT

Parameters

KeyRef

Type: keyref

The keyref that refers to the key.

Expand image Property Value/Return Value

Type: Integer

The number of fields that have been defined in the key.

Expand image See Also

Reference

KeyRef Data Type


FIELDINDEX Function (KeyRef)

FIELDINDEX Function (KeyRef)
See Also
CollapseAll image

Returns the fieldref of the field that has this index in the key referred to by the keyref variable. Returns an error if no key is selected.

FieldRef := KeyRef.FIELDINDEX(Index)

Parameters

KeyRef

Type: keyref

The keyref that refers to the key.

Index

Type: Integer

The input index.

Expand image Property Value/Return Value

Type: fieldref

The fieldref that refers to the field with this index in the key.

Expand image Remarks

The first field in the index must have index 1, the second index 2, and so on. The last field must have index = FIELDCOUNT. If the index is out of the range supplied or if no table is selected, the function returns an error.

Expand image See Also

Reference

KeyRef Data Type


RECORD Function (KeyRef)

RECORD Function (KeyRef)
See Also
CollapseAll image

Returns a recordref for the current record referred to by the key. Returns an error if no key is selected.

RecordRef := KeyRef.RECORD

Parameters

KeyRef

Type: keyref

The keyref that refers to the key that is currently selected.

Expand image Property Value/Return Value

Type: recordref

The recordref of the record that is currently selected.

Expand image See Also

Reference

KeyRef Data Type


Numbers

Numbers

This section contains the following topics:

  • BigInteger Data Type

  • Decimal Data Type

  • Integer Data Type

  • Numeric Functions


BigInteger Data Type

BigInteger Data Type
See Also Example
CollapseAll image

Stores very large whole numbers that range from -9,223,372,036,854,775,807 to 9,223,372,036,854,775,807.

Expand image Remarks

This data type is a 64-bit integer.

You must add an L to the constant definition to inform C/AL that the integer must be interpreted and treated as a BigInteger.

If you assign -9,223,372,036,854,775,808 directly to a BigInteger variable, then you get an error when you try to compile the code. However, you can indirectly assign -9,223,372,036,854,775,808 to a BigInteger variable by using the following code.

CopyCode image Copy Code
BigIntegerVar := -9223372036854775807L;
BigIntegerVar := BigIntegerVar - 1;

If you try to indirectly assign a value that is smaller than -9,223,372,036,854,775,808, or larger than 9,223,372,036,854,775,807, then you get a run-time error.

Expand image Example

CopyCode image Copy Code
BI := 1L;
BI := 455500000000L;

Expand image See Also

Reference

Decimal Data Type
Integer Data Type
ABS Function (Decimal, Integer, BigInteger)
POWER Function (Decimal, Integer, BigInteger)
RANDOM Function (Integer)
RANDOMIZE Function (Integer)
ROUND Function (Decimal)


Decimal Data Type

Decimal Data Type
See Also Example
CollapseAll image

This simple data type denotes decimal numbers ranging from -999,999,999,999,999.99 to +999,999,999,999,999.99.

Expand image Example

The following are examples of decimal values.
CopyCode image Copy Code
546.88
3425.57

The following is not a decimal, but rather an Integer Data Type.
CopyCode image Copy Code
342

Expand image Changes from Previous Versions

In Microsoft Dynamics NAV 2009, the Decimal data type is mapped to the Microsoft .NET Framework common language runtime (CLR) Decimal data type and the precision and limits behave slightly differently than the Binary Coded Decimal (BCD) data type in previous versions of C/AL. This example shows how decimal data types are different in Microsoft Dynamics NAV 2009.

The following table shows the limits for variables of type DECIMAL in Microsoft Dynamics NAV 2009 and in previous versions.

Limit Microsoft Dynamics NAV 2009 Previous versions of Microsoft Dynamics NAV

Maximum format value.

This is the maximum value that can be:

  • Formatted into a TEXT variable by the FORMAT function

  • Input from the UI or XMLPorts

  • Assigned directly in source code

+/- 999,999,999,999,999.99

+/- 999,999,999,999,999.99

Maximum field data type value.

This is the maximum value that a field variable in a record can hold while not being persisted.

+/- 999,999,999,999,999.99

+/- (9,99999999999999E+63)

Maximum persisted value.

This is the maximum value that can be stored in the database.

SQL server limit: Can read previous stored values but cannot store values outside the formatting range since field variables cannot be assigned values outside the formatting range.

Native database limit: not supported

SQL server limit: +/- 999.999.999.999.999.999,99

Native database limit: +/- (9,99999999999999E+63)

Maximum calculating value.

This is the maximum value that can be calculated by code statements while not assigning to a field variable, storing to the database, or formatting to a text variable.

+/- 79,228,162,514,264,337,593,543,950,335

+/- (9,99999999999999E+63)

This table shows that the maximum safe value that will work on all versions of Microsoft Dynamics NAV is +/- 999,999,999,999,999.99.

It is possible to assign to a variable the maximum value that can be formatted and then multiply that variable by a large positive number, thereby generating a greater value. However, we do not recommend doing this. If you do, you will get errors if you attempt to format this variable to a text variable or assign the variable to a field variable in a record.

Expand image See Also

Reference

BigInteger Data Type
Integer Data Type
ABS Function (Decimal, Integer, BigInteger)
POWER Function (Decimal, Integer, BigInteger)
RANDOM Function (Integer)
RANDOMIZE Function (Integer)
ROUND Function (Decimal)


Integer Data Type

Integer Data Type
See Also Example
CollapseAll image

This simple data type stores whole numbers with values that range from -2,147,483,647 to 2,147,483,647.

Expand image Remarks

In addition to representing whole numbers in this range, you can use integers to represent Boolean values. For Boolean values, -1 represents true and 0 represents false.

If you assign -2,147,483,648 directly to an Integer variable, then you get an error when you try to compile the code. However, you can indirectly assign -2,147,483,648 to an Integer variable by using the following code.

CopyCode image Copy Code
IntegerVar := -2147483647;
IntegerVar := IntegerVar - 1;

If you try to indirectly assign a value that is smaller than -2,147,483,648 or larger than 2,147,483,647, then you get a run-time error.

Expand image Example

The following are examples of integer values.
CopyCode image Copy Code
546
-3425

The following example is a decimal and not an integer.
CopyCode image Copy Code
342.45

Expand image See Also

Reference

BigInteger Data Type
Decimal Data Type
ABS Function (Decimal, Integer, BigInteger)
POWER Function (Decimal, Integer, BigInteger)
RANDOM Function (Integer)
RANDOMIZE Function (Integer)
ROUND Function (Decimal)


Numeric Functions

Numeric Functions

This section contains the following topics:

  • ABS Function (Decimal, Integer, BigInteger)

  • POWER Function (Decimal, Integer, BigInteger)

  • RANDOM Function (Integer)

  • RANDOMIZE Function (Integer)

  • ROUND Function (Decimal)


ABS Function (Decimal, Integer, BigInteger)

ABS Function (Decimal, Integer, BigInteger)
See Also Example
CollapseAll image

Calculates the absolute value of a number (Decimal, Integer or BigInteger). ABS always returns a positive numeric value or zero.

NewNumber := ABS(Number)

Parameters

Number

Type: Integer

The input value.

Expand image Property Value/Return Value

Type: Integer

The return value is greater than or equal to 0 (zero).

Expand image Remarks

The system automatically converts all of the numeric data types for you.

Expand image Example

This example shows how to remove the sign from a negative numeric value. This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType
x | Decimal
y | Decimal
Text constant name | ENU Value
Text000 | x = %1, y = %2
CopyCode image Copy Code
x := -10.235; // x is assigned a negative value
y := ABS(x); // y is assigned the value of x without sign
MESSAGE(Text000, x, y);

The message window displays the following:

x = -10.235, y = 10.235

Expand image See Also

Reference

POWER Function (Decimal, Integer, BigInteger)
RANDOM Function (Integer)
RANDOMIZE Function (Integer)
ROUND Function (Decimal)


POWER Function (Decimal, Integer, BigInteger)

POWER Function (Decimal, Integer, BigInteger)
See Also Example
CollapseAll image

Raises a number to a power. For example, you can use this function to square the number 2 to get the result of 4.

NewNumber := POWER(Number, Power)

Parameters

Number

Type: Integer

The number you want to raise exponentially. This number is the base in the exponential function.

Power

Type: Integer

The exponent in the exponential function.

Expand image Property Value/Return Value

Type: Decimal

The result of raising Number by Power.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
Number1 | Decimal
Power1 | Decimal
Result1 | Decimal
Text constant name | Constant value
Text000 | %1 raised to the power of %2 = %3
CopyCode image Copy Code
Number1 := 64;
Power1 := 0.5;
Result1 := POWER(Number1, Power1);
MESSAGE(Text000, Number1, Power1, Result1)

On a computer with the regional format set to English (United States), the first message window displays the following:

64 raised to the power of 0.5 = 8

This example shows that raising a number to the power of 0.5 corresponds to the square root of the number.

This example shows a typical use for the POWER function.

If a principal amount P is deposited at interest rate R and compounded annually, then at the end of N years, the accumulated amount (A) is:

A = P(1 + R)N

For example, you place LCY 2800 into a bank account that pays 5 percent, which is compounded quarterly. To determine what the amount will be in eight years, you must consider:

N = 32 payment periods (8 years times 4 quarterly periods)

R = 0.0125 per period (5 percent divided by 4 quarterly periods)

The accumulated amount A is:

A = LCY 2800(1 + 0.0125)32 =LCY 2800(1.4881) = LCY 4166.77

If a principal amount P is deposited at the end of each year at interest rate R (in decimal notation) compounded annually, then at the end of N years, the accumulated amount is:

A = P[((1 + R)N - 1)/R]

This is typically called an annuity.

For example, you have an annuity in which a payment of LCY 500 is made at the end of each year. The interest on this annuity is 4 percent, which is compounded annually. To determine what the annuity will be worth in 20 years, you must consider:

R = 0.04

N = 20

The amount of the annuity A will be:

A = LCY 500[((1 + 0.04)20 - 1)/0.04 = LCY 14,889.04

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType
P | Decimal
R | Decimal
N | Decimal
A | Decimal
FormatString | Text
Text constant name | Constant value
Text000 | Principal $%1 at a 5 percent interest rate is compounded quarterly.\
Text001 | (Rate = %2)\
Text002 | The amount after %3 years = $%4.
Text003 | Principal $%1 is deposited at the end of each year at a 4 percent interest rate, compounded annually.\
Text004 | (Rate = %2)\
Text005 | The amount after %3 years = $%4.
CopyCode image Copy Code
FormatString := '<Precision,2><Standard Format,1>';
// Example 1
P := 2800;
R := 0.0125;
N := 32;
A = P * (POWER(1 + R, N));
MESSAGE(Text000 + Text001 + Text002, P, R, N, FORMAT(A,0,FormatString);
// Example 2
P = 500;
R = 0.04;
N = 20;
A = P * ((POWER(1 + R, N) - 1)/R);
MESSAGE(Text001, P, R, N, FORMAT(A,0,FormatString));

On a computer with the regional format set to English (United States), the first message window displays the following:

Principal $2,800 at a 5 percent interest rate is compounded quarterly.

(Rate = 0.0125)

The amount after 32 years = $4166.77.

The second message window displays the following:

Principal $500 is deposited at the end of each year at a 4 percent interest rate, compounded annually.

(Rate = 0.04)

The amount after 20 years = $14889.04.

Expand image See Also

Reference

ABS Function (Decimal, Integer, BigInteger)
RANDOM Function (Integer)
RANDOMIZE Function (Integer)
ROUND Function (Decimal)


RANDOM Function (Integer)

RANDOM Function (Integer)
See Also
CollapseAll image

Returns a pseudo-random number.

Number := RANDOM(MaxNumber)

Parameters

MaxNumber

Type: Integer

The largest acceptable number. In effect, you are setting a range from one (1) to the number you specify with the MaxNumber parameter.

Expand image Property Value/Return Value

Type: Integer

A pseudo-random number between one (1) and the number you entered for MaxNumber.

Expand image Remarks

If MaxNumber is negative it acts as a positive.

If MaxNumber is zero this function always returns 1.

A number is always chosen from the same set of numbers. Use RANDOMIZE Function (Integer) to generate a new set of numbers.

Expand image See Also

Reference

ABS Function (Decimal, Integer, BigInteger)
POWER Function (Decimal, Integer, BigInteger)
RANDOMIZE Function (Integer)
ROUND Function (Decimal)


RANDOMIZE Function (Integer)

RANDOMIZE Function (Integer)
See Also
CollapseAll image

Generates a set of random numbers from which the RANDOM Function (Integer) will select a random number.

RANDOMIZE([Seed])

Parameters

Seed

Type: Integer

A number used to create a unique set of numbers.

Expand image Remarks

If you use the same number as seed, the same set of numbers is generated. If you omit this optional parameter, RANDOMIZE uses the current system time (total number of milliseconds since midnight).

Furthermore, the random generator is specific to each connection so the sequence of numbers that is returned when you call the RANDOM function will be the same after each call to RANDOMIZE with a specific seed.

Note Note

The sequences of numbers that are returned will not be the same in the Classic client and in the RoleTailored client.

Expand image See Also

Reference

ABS Function (Decimal, Integer, BigInteger)
POWER Function (Decimal, Integer, BigInteger)
RANDOM Function (Integer)
ROUND Function (Decimal)


ROUND Function (Decimal)

ROUND Function (Decimal)
See Also Example
CollapseAll image

Rounds the value of a numeric variable.

NewNumber := ROUND(Number [, Precision] [, Direction])

Parameters

Number

Type: Decimal

The number that you want to round.

Precision

Type: Decimal

This optional parameter determines the precision used when rounding. If you do not specify a Precision parameter, then the following steps are used to specify the precision:

  1. The function ReadRounding in Codeunit 1, Application Management, is called. ReadRounding returns a decimal value that is the precision. By default, the ReadRounding function returns the Amount Rounding Precision field from the GLSetup table.

  2. If you have customized Codeunit 1 and it does not implement the ReadRounding function, then the No. of digits after decimal in the Regional and Language Options on the current computer is used to specify the precision. If the No. of digits after decimal does not specify a valid value, then the precision is specified as 2 digits after the decimal.

Direction

Type: Text or Code

This optional parameter specifies how to round the Number parameter. The default rounding method is '='. The following are the options for rounding:

  • '=' rounds up or down to the nearest value (default). Values of 5 or greater are rounded up. Values less than 5 are rounded down.

  • '>' rounds up

  • '<' rounds down

Expand image Property Value/Return Value

Type: Decimal

The rounded result.

Expand image Example

This example shows how to use the ROUND function. This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType
DecimalToRound | Decimal
Direction | Text
Precision | Decimal
Result | Decimal
Text Constant | ENU Value
Text000 | ROUND(%1, %2, %3) returns %4.
CopyCode image Copy Code
DecimalToRound := 1234.56789;
Direction := '>';
Precision := 0.001;
Result := ROUND(DecimalToRound, Precision, Direction);
MESSAGE(Text000, Format(DecimalToRound,0,1), Precision, Direction, Result);

On a computer with the regional format set to English (United States), the message window displays the following:

ROUND(1234.56789, 0.001, >) returns 1,234.568

The following table displays some additional ROUND examples.

Number | Precision | Direction | Rounded number
1234.56789 | 100 | = | 1200
1234.56789 | 0.1 | = | 1234.6
1234.56789 | 0.001 | = | 1234.568
1234.56789 | 0.001 | < | 1234.567
1234.56789 | 0.001 | > | 1234.568
-1234.56789 | 100 | = | -1200
-1234.56789 | 0.1 | = | -1234.6
-1234.56789 | 0.001 | = | -1234.568
-1234.56789 | 0.001 | < | -1234.567
-1234.56789 | 0.001 | > | -1234.568

When you round down ('<') a negative number, the following occurs: -1234.56789 is rounded down to -1234.567. However, -1234.567 is a mathematically greater value than -1234.56789.

When you round up ('>') a negative number, the following occurs: -1234.56789 is rounded up to -1234.568. However, -1234.568 is a mathematically smaller value than -1234.56789.

Expand image See Also

Reference

ABS Function (Decimal, Integer, BigInteger)
POWER Function (Decimal, Integer, BigInteger)
RANDOM Function (Integer)
RANDOMIZE Function (Integer)


OCX Data Type

OCX Data Type

Used to reference a custom control (OCX, ActiveX Control).

Expand image Remarks

In order to use a control in C/SIDE, define a variable of type OCX and give it a name. Then use the lookup in the Subtype field to locate and select the control you want to use. You select from a list of installed controls, and when you select one, the GUID of the control is inserted. When the focus leaves the Subtype field, the name of the control is substituted for the GUID.

When you have defined a control as a variable, you can use the control through the variable, and you can browse its methods and properties in the Symbol Menu.

When you are using a control, you should know that there is not a one-to-one relationship between C/AL data types and COM data types. For an overview of the data type mapping, see Using COM Technologies in C/SIDE.


Option Data Type

Option Data Type
Example
CollapseAll image

This simple data type denotes an option value.

Expand image Remarks

In the OptionString Property of the field or variable, you can enter the option values as a comma-separated list. The Option type is a zero-based enumerator type, which means that the option values are assigned to sequential numbers, starting with 0. You can convert option data types to integers.

For more information about option variables in multilanguage-enabled applications, see Developing Multilanguage-Enabled Applications.

Expand image Example

In the Purchase Header table, the Status field is an Option data type. In the following example, the option value is converted into an integer. This example requires that you create the following variables.

Name | Data type | Subtype
Number | Integer |
PurchHeaderRec | Record | Purchase Header
CopyCode image Copy Code
Number := PurchHeaderRec."Document Type";

This example shows how you can use the value of an option field as a constant in your C/AL code.
CopyCode image Copy Code
PurchHeaderRec."Document Type" := PurchHeaderRec."Document Type"::Invoice;


Page Data Type

Page Data Type

This complex data type stores pages.

Expand image Remarks

Pages contain a number of simpler elements called controls. Controls are used to display information to the user or receive information from the user. Pages can only be displayed on the RoleTailored client.

Expand image See Also

Reference

PAGE.RUN Function
PAGE.RUNMODAL Function
RUN Function (Page)
RUNMODAL Function (Page)


PAGE.RUN Function

PAGE.RUN Function
See Also Example
CollapseAll image

Creates and launches a page object, which you specify.

PAGE.RUN(Number[, Record] [, Field])

Parameters

Number

Type: Integer

The number of the page that you want to run. If you enter zero (0), the system displays the default lookup window for the current page. Click View, click C/AL Symbols Menu to select the page from a list.

If the page you specify does not exist, a run-time error occurs.

Record

Type: Record

The Page.RUN function shows, by default, the record last displayed on the page. For each object, the system stores information about the most recently displayed record and the attached key and filters.

Use this optional parameter to select a specific record to display on the page. The record must be of the same type as the table attached to the window. When the record is displayed, the key and filters attached to the record are used.

Field

Type: Field

Use this optional parameter to select a specific field on which focus will be placed.

Expand image Remarks

If, at design time, you do not know the specific page you want to run, use this function or the PAGE.RUNMODAL function.

If you do know which page you want to run, you can use the RUN (Form) or RUNMODAL (Form) function to specify a variable.

When you want to close the page, use CurrPage.CLOSE. CurrForm is a predefined system variable.

It is important to remember that pages that have been created by transforming existing forms still use the same code as the original forms. Furthermore, when you compile your code to C#, forms and pages are both treated as forms.

If, from a page, you call another form that does not have a corresponding page, you will receive an error message.

If you run this page function on a Classic client, you receive an error because the Classic client does not support pages.

Expand image Example

CopyCode image Copy Code
IF IsServiceTier THEN
  Page.RUN(4711);
ELSE
  Form.Run(4711);

Expand image See Also

Reference

Page Data Type


PAGE.RUNMODAL Function

PAGE.RUNMODAL Function
See Also Example
CollapseAll image

Creates, runs, and closes a specified page object. When a page is run modally, no input (keyboard or mouse click) can occur except to objects on the modal page.

[Action :=] Page.RUNMODAL(Number[, Record][, Field])

Parameters

Number

Type: Integer

The number of the page that you want to run. If you enter zero (0), the default lookup window for the current page is displayed. Click View and then click C/AL Symbols Menu to select the page from a list.

If the page you specify does not exist, a run-time error occurs.

Record

Type: Record

This function shows, by default, the record last displayed on the page. For each object, the system stores information about the most recently shown record and the attached key and filters.

Use this optional parameter to select a specific record to display on the page. The record must be of the same type as the table attached to the page. When the record is displayed, the key and filters attached to the record are used.

Field

Type: Field

Use this optional parameter to select a specific field on which focus will be placed.

Expand image Property Value/Return Value

Type: Code

Specifies what action the user took. The following table shows the possible return values.

Return value | Description
OK | The user selected OK to exit the window
Cancel | The user selected Cancel to exit the window
LookupOK | The user selected OK on a lookup window
LookupCancel | The user selected Cancel on a lookup window
Yes | The user selected Yes
No | The user selected No
Close | The user selected Close, ESC, or closed the window using the title bar
FormHelp | The user selected Help
RunObject | The user selected an option that ran another object
RunSystem | The user selected an option that ran an external program

Expand image Remarks

The page is run modally. If, at design time, you do not know the specific page you want to run, then use this function or the PAGE.RUN Function.

If you do know the specific page you want to run, then you can use the RUN Function (Page) or RUNMODAL Function (Page) to specify a variable.

When you want to close the page, use CurrPage.CLOSE. CurrPage is a predefined system variable.

It is important to remember that pages that have been created by transforming existing forms still use the same code as the original forms. Furthermore, when you compile your code to C#, forms and pages are both treated as forms.

If, from a page, you call another form that does not have a corresponding page, you will receive an error message.

If you run this page function on a Classic client, you receive an error because the Classic client does not support pages.

Expand image Example

This example shows how to call page 4711.
CopyCode image Copy Code
IF IsServiceTier THEN
  Page.RUNMODAL(4711, MyRecord, ...);
ELSE
  IF Form.RUNMODAL(4711, MyRecord, ...) = Action::LookupOK THEN...;

Expand image See Also

Reference

Page Data Type


RUN Function (Page)

RUN Function (Page)
See Also Example
CollapseAll image

Creates and launches a page that you specify. You can use CLEAR Function to remove the page.

Page.RUN

Parameters

Page

Type: Page

After you define this variable, you can run the following page functions:

  • SETTABLEVIEW

  • SETRECORD

  • GETRECORD

  • RUN

  • RUNMODAL.

The variable is automatically cleared after this function is executed.

If the page you specify does not exist, you receive a compile error.

Expand image Remarks

If, at design time, you know the specific page that you want to run, use this function or the RUNMODAL Function (Page).

If you do not know the page that you want to run, use the PAGE.RUN Function or the PAGE.RUNMODAL Function.

After you define the page variable, you can use it before you run the page. If you use the RUNMODAL Function (Page), you can use the variable before and after you run the page.

Expand image Example

This example shows how to use the RUN function. Assume the variable MyPage has been defined as Page 1.
CopyCode image Copy Code
MyPage.XXX; // any user-defined function
MyPage.SETTABLEVIEW(MyRecord);
MyPage.SETRECORD(MyRecord);
MyPage.RUN;

Expand image See Also

Reference

Page Data Type


RUNMODAL Function (Page)

RUNMODAL Function (Page)
See Also Example
CollapseAll image

Creates, launches, and closes a page that you specify. When a page is run modally, no input (keyboard or mouse click) can occur except to objects on the modal page.

[Action :=] Page.RUNMODAL

Parameters

Page

Type: Variable

After you define this variable, you can run the following page functions:

  • SETTABLEVIEW

  • SETRECORD

  • GETRECORD

  • RUN

  • RUNMODAL

Unlike the PAGE.RUN Function, the variable is not automatically cleared after this function executes.

If the page you specify does not exist, a compilation error occurs.

Expand image Property Value/Return Value

Type: Code

This optional return value specifies what action the user took. The following table shows the possible return values.

Return value | Description
OK | The user selected OK to exit the window
Cancel | The user selected Cancel to exit the window
LookupOK | The user selected OK on a lookup window
LookupCancel | The user selected Cancel on a lookup window
Yes | The user selected Yes
No | The user selected No
Close | The user selected Close, ESC, or closed the window using the title bar
FormHelp | The user selected Help
RunObject | The user selected an option that ran another object
RunSystem | The user selected an option that ran an external program

Expand image Remarks

If you know at design time the exact page that you want to run, use this function or the RUN Function (Page).

If you do not know at design time the exact page that you want to run, use the PAGE.RUN Function or the PAGE.RUNMODAL Function.

After you define the page variable, you can use it before and after you run the page. If you use the PAGE.RUN Function, you can only use the variable before you run the page.

Expand image Example

This example shows how to use this function. Assume that the variable SomePage has been defined as Page 1.
CopyCode image Copy Code
CLEAR(SomePage)
SomePage.XXX; // any user-defined function
SomePage.SETTABLEVIEW(MyRecord);
SomePage.SETRECORD(MyRecord);
IF SomePage.RUNMODAL = Action::LookupOK THEN
  SomePage.GETRECORD(MyRecord)...

Note that this code example includes the CLEAR Function to ensure the variable has been cleared.

Expand image See Also

Reference

Page Data Type


Record Data Type

Record Data Type

This complex data type corresponds to a row in a table. Each record consist of fields that form the columns of the table. A record is typically used to hold information about a fixed number of properties.

Expand image Remarks

To access a field in a table in your C/AL code, use the following syntax: TableName.FieldName

Expand image See Also

Reference

ADDLINK Function (Record)
ASCENDING Function (Record)
CALCFIELDS Function (Record)
CALCSUMS Function (Record)
CHANGECOMPANY Function (Record)
CLEARMARKS Function (Record)
CONSISTENT Function (Record)
COPY Function (Record)
COPYFILTER Function (Record)
COPYFILTERS Function (Record)
COPYLINKS Function (Record)
COUNT Function (Record)
COUNTAPPROX Function (Record)
CURRENTKEY Function (Record)
DELETE Function (Record)
DELETEALL Function (Record)
DELETELINK Function (Record)
DELETELINKS Function (Record)
FIELDACTIVE Function (Record)
FIELDCAPTION Function (Record)
FIELDERROR Function (Record)
FIELDNAME Function (Record)
FIELDNO Function (Record)
FILTERGROUP Function (Record)
FIND Function (Record)
FINDFIRST Function (Record)
FINDLAST Function (Record)
FINDSET Function (Record)
GET Function (Record)
GETFILTER Function (Record)
GETFILTERS Function (Record)
GETPOSITION Function (Record)
GETRANGEMAX Function (Record)
GETRANGEMIN Function (Record)
GETVIEW Function (Record)
HASFILTER Function (Record)
HASLINKS Function (Record)
INIT Function (Record)
INSERT Function (Record)
ISEMPTY Function (Record)
LOCKTABLE Function (Record)
MARK Function (Record)
MARKEDONLY Function (Record)
MODIFY Function (Record)
MODIFYALL Function (Record)
NEXT Function (Record)
READCONSISTENCY Function (Record)
READPERMISSION Function (Record)
RECORDLEVELLOCKING Function (Record)
RELATION Function (Record)
RENAME Function (Record)
RESET Function (Record)
SETCURRENTKEY Function (Record)
SETFILTER Function (Record)
SETPERMISSIONFILTER Function (Record)
SETPOSITION Function (Record)
SETRANGE Function (Record)
SETRECFILTER Function (Record)
SETVIEW Function (Record)
TABLECAPTION Function (Record)
TABLENAME Function (Record)
TESTFIELD Function (Record)
TRANSFERFIELDS Function (Record)
VALIDATE Function (Record)
WRITEPERMISSION Function (Record)


ADDLINK Function (Record)

ADDLINK Function (Record)
See Also
CollapseAll image

Adds a link to a record.

[ID := ]ADDLINK(URL[, Description])

Parameters

URL, Description

Type: String

The link that you want to add to the record and an optional description of that link.

Expand image Property Value/Return Value

Type: Integer

The ID of the URL that you want to add to the record.

Expand image Remarks

When you add a link to a form or a table, an entry is created in the Record Link system table. Each entry is given an ID.

The URL can be a link to a Web site, a file stored on the local or on a remote computer, or a link to a Microsoft Dynamics NAV form.

Expand image See Also

Reference

Record Data Type


ASCENDING Function (Record)

ASCENDING Function (Record)
See Also
CollapseAll image

Changes the order in which the system will search through a C/SIDE table, or returns the current order.

[IsAscending :=] Record.ASCENDING([SetAscending])

Parameters

SetAscending

Type: Boolean

Specifies the order of the search.

If this parameter is true, the search is done in ascending order. If this parameter is false, the search is done in descending order. If you do not use this parameter, the function returns the current search order.

Expand image Property Value/Return Value

Type: Boolean

The order in which a search will be done.

true if the search will be done in ascending order; otherwise, false.

Expand image See Also

Reference

Record Data Type


CALCFIELDS Function (Record)

CALCFIELDS Function (Record)
See Also Example
CollapseAll image

Updates the FlowFields in a record.

[Ok :=] Record.CALCFIELDS(Field1, [Field2],...)

Parameters

Field1, Field2, …

Type: Field

The FlowFields that you want to update. Each field must be defined as a FlowField and must belong to the same record variable.

Expand image Property Value/Return Value

Type: Boolean

Expand image Remarks

FlowFields are virtual fields. The values in these fields are not saved in the table. This means that you must use the CALCFIELDS function to update them. For example, if you retrieve a record using the FIND Function (Record) and NEXT Function (Record), the FlowFields in those records are set to zero (0). Then, when you call CALCFIELDS, their values are updated.

When a FlowField is a direct source expression of a control on a form or a report, the calculation will be performed automatically.

You can also use the CALCFIELDS function to calculate binary large objects (BLOBs). For more information, see BLOB Data Type.

Expand image Example

This example shows how to use the CALCFIELDS function to find the balance on December 31, 2008 and the net change for a customer in 2008.

This example requires that you create the following variable.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerRec.SETRANGE("Date Filter",010108D,123108D);
CustomerRec.CALCFIELDS(Balance, "Net Change");

The first line sets up a filter for the date filter field in the customer record. This field is a FlowFilters field which is used to calculate some of the FlowFields in the customer record. In the second line, the FlowFields are calculated.

Expand image See Also

Reference

FlowFields
Record Data Type


CALCSUMS Function (Record)

CALCSUMS Function (Record)
See Also Example
CollapseAll image

Calculates the total of a column of SumIndexFields in a C/SIDE table. Using parameters, you can specify which fields to calculate.

[Ok :=] Record.CALCSUMS (Field1, [Field2],...)

Parameters

Record

Type: Record

The record that contains the SumIndexFields that you want to calculate.

Field1, Field2, …

Type: Decimal

The fields that you want to calculate. Each field is a decimal field, defined as a SumIndexField, in the current key.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value and if one of the fields is not a SumIndexField, a run-time error occurs. If you include a return value, you must handle any errors.

Expand image Remarks

Use this function to total columns in a table. This function operates only on records that meet the conditions of any filters associated with the record.

Expand image Example

This example shows how to use the CALCSUMS function.
CopyCode image Copy Code
"Cust. Ledger Entry".SETCURRENTKEY("Customer No.","Date");
"Cust. Ledger Entry".SETRANGE("Customer No.", 'AAA 1050');
"Cust. Ledger Entry".SETRANGE("Date", 010196D, 123196D);
"Cust. Ledger Entry".CALCSUMS("Amount");

The first line selects a key. The second and third lines set filters for the fields Customer No. and Date in the Cust. Ledger Entry record so the total is only calculated within the specified range. The CALCSUMS function then finds the net change in account AAA 1050 for 1996. The Amount field will show the result of the calculation.

Expand image See Also

Reference

Record Data Type


CHANGECOMPANY Function (Record)

CHANGECOMPANY Function (Record)
See Also Example
CollapseAll image

Redirects references to table data from one company to another.

[Ok :=] Record.CHANGECOMPANY([CompanyName])

Parameters

Record

Type: Record

The record that you want to access from a table in another company.

CompanyName

Type: Text or code

The name of the company to which you want to change. If you omit this parameter, you change back to the current company.

Expand image Property Value/Return Value

Type: Boolean

true if the company was found; otherwise, false.

If you omit this optional return value and the company cannot be found, a run-time error occurs. If you include the return value, you must handle any errors.

Expand image Remarks

When executing this function, the user's access rights are respected. For example, a user cannot access data in CompanyName unless he already has the necessary access rights.

The CHANGECOMPANY function is not affected by the RESET Function (Record). You can deselect a company by making a new call to CHANGECOMPANY or by using the CLEAR Function.

Global filters always belong to a specific company. If you use the following code to select the company named NewCompany, any filters assigned to Record will be transferred to Record in the new company.

CopyCode image Copy Code
Record.CHANGECOMPANY(NewCompany);

Even if you run the CHANGECOMPANY function, triggers still run in the current company, not in the company that you specified in the CHANGECOMPANY function.

Expand image Example

This example shows how to use the CHANGECOMPANY function.
CopyCode image Copy Code
"G/L Account".CHANGECOMPANY('New Company');
"G/L Account".GET('1000');
"G/L Account".CALCFIELDS(Balance); // Calculates the balance
// for account no. 1000 in 'New Company'
"G/L Entry".CHANGECOMPANY('New Company');
"G/L Entry".SETCURRENTKEY("Entry No.","Posting Date");
"G/L Entry".SETRANGE("Entry No.",1000);
"G/L Entry".SETRANGE("Posting Date",010196D,013196D);
"G/L Entry".CALCSUMS(Amount); // Sums Amount from
// all G/L entries on account no. 1000 within the specified range,
// for 'New Company'
"G/L Entry".RESET;
"G/L Entry".FIND('+'); // Finds the largest "No." in the G/L Entry
// table in 'New Company'
"G/L Entry".DELETE; // Deletes this entry in 'New Company'

This example shows that after the CHANGECOMPANY function has been called, all future references to the G/L Account and G/L Entry tables will refer to the table data in New Company.

This example shows that CHANGECOMPANY only changes the company on a data level. Triggers and functions will still run in the context of the current company.
CopyCode image Copy Code
Rec.CHANGECOMPANY('B');
Rec.FINDFIRST;
Rec.MODIFY(TRUE);

If you run the code in this example from Company A, it will modify Rec in Company B, but it will run the OnModify trigger in Company A.

Expand image See Also

Reference

Record Data Type


CLEARMARKS Function (Record)

CLEARMARKS Function (Record)
See Also Example
CollapseAll image

Removes all the marks from a record.

Record.CLEARMARKS

Parameters

Record

Type: Record

The record from which you want to remove all marks.

Expand image Example

This example requires that you create a CustomerRec variable that has DataType of Record and Subtype of Customer.
CopyCode image Copy Code
CustomerRec.CLEARMARKS

Expand image See Also

Reference

Record Data Type


CONSISTENT Function (Record)

CONSISTENT Function (Record)
See Also Example
CollapseAll image

Marks a C/SIDE table as being consistent or inconsistent.

Record.CONSISTENT(Consistent)

Parameters

Record

Type: Record

The table that you want to mark.

Consistent

Type: Boolean

The mark to be set on the table.

If this parameter is true, the table is marked as consistent. If this parameter is false, the table is marked as inconsistent.

Expand image Remarks

Usually this function is only used for accounting routines. If your accounts do not balance, the accounts are inconsistent. This function ensures that inconsistent changes are not made in your accounts.

If an attempt is made to commit a write transaction when a table is marked as inconsistent, a message is displayed and all updates made in the write transaction are aborted.

Expand image Example

A typical example of an inconsistency occurs when the sum of all the entries in a table containing general ledger entries does not balance (is not equal to zero).

In this example, your application includes a function object called ChangeAmount. This function is used to withdraw amounts that were put into the General Ledger Entry table in your application. When an amount is withdrawn from an account, the system is inconsistent until a corresponding amount is put in. The following code example illustrates the ChangeAmount function. The ChangeAmount function has one parameter, Amount, which is a Decimal data type.
CopyCode image Copy Code
GLEntry."G/L Account No." := '1000';
GLEntry.Amount := Amount;
GLEntry.INSERT;
Balance := Balance + Amount;
IF Balance = 0 THEN
  Consistent := TRUE
ELSE
  Consistent := FALSE;
GLEntry.CONSISTENT(Consistent);
END;

The function uses the variable Balance to express the change in balance. For example, when the function is used to withdraw $100, the Balance variable will reflect this as -$100.

When you use the function to put in one or more amounts whose total equals +$100, the Balance variable then equals zero and the table is marked as consistent. This means that if an attempt is made to put in an amount and end the write transaction (commit the change) without withdrawing a corresponding amount, an error occurs and the write transaction is canceled.

Expand image See Also

Reference

Record Data Type


COPY Function (Record)

COPY Function (Record)
See Also
CollapseAll image

Copies a record from a C/SIDE table. All filters, marks, and keys are included in the copy.

Record.COPY(FromRecord [, ShareTable])

Parameters

Record

Type: Record

The record where the copy will be placed.

FromRecord

Type: Record

The record that you want to copy.

ShareTable

Type: Boolean

Specifies whether the function creates a copy of the record or creates a reference to a temporary record.

If FromRecord and Record are both temporary and ShareTable is true, then the COPY function does not create a new copy of the record. Instead, the COPY function causes Record to reference the same table as FromRecord.

The default value is false. If you specify false, all records are copied to Record from FromRecord.

Expand image Comments

If ShareTable is true, both Record and FromRecord must be temporary; otherwise an error will occur.

Expand image See Also

Reference

Record Data Type


COPYFILTER Function (Record)

COPYFILTER Function (Record)
See Also Example
CollapseAll image

Copies the filter that has been set for one field and applies it to another field.

Record.COPYFILTER(FromField, ToRecord.ToField)

Parameters

Record

Type: Record

The record from which to copy the filter.

FromField

Type: Field

The field from which the filter will be copied.

ToRecord.ToField

Type: Record.Field

The record and field to which you want to apply the copied filter.

Expand image Remarks

The FromFields and ToFields must be of the same data type, but they do not have to belong to the same table.

Expand image Example

This example requires that you create a Record variable for the Customer table named Customer and an Integer variable named Count.
CopyCode image Copy Code
Customer.SETFILTER("No.", '<1000');
Customer.COPYFILTER("No.", Vendor."No.");
.
.
Count := Vendor.COUNT;

The filter set for Customer."No." is copied and applied to Vendor."No.". This affects the result of the COUNT Function (Record), which counts how many vendors have a number less than 1000.

Expand image See Also

Reference

COPYFILTERS Function (Record)
Record Data Type


COPYFILTERS Function (Record)

COPYFILTERS Function (Record)
See Also Example
CollapseAll image

Copies all the filters set by the SETFILTER Function (Record) or the SETRANGE Function (Record) from one record to another.

Record.COPYFILTERS(FromRecord)

Parameters

Record

Type: Record

The record to which you want to copy filters.

FromRecord

Type: Record

The record from which you want to copy filters.

Expand image Remarks

This function is used to apply the filters defined for one record to another record. The filters are used as a basis for counting, searching, calculating, or a similar operation.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType | Subtype
Customer1 | Record | Customer
Customer2 | Record | Customer
Count | Integer |
CopyCode image Copy Code
// Set filters on fields in a Customer record
Customer1.SETFILTER("No.", '<1000');
Customer1.SETRANGE("Credit Limit (LCY)", 10000, 20000);
Customer1.MARKEDONLY(TRUE);
// Apply filters to another record
Customer2.COPYFILTERS(Customer1);
Count := Customer2.COUNT;

The filters defined for Customer1 are copied and applied to Customer2. This affects the result returned by the COUNT Function (Record).

Expand image See Also

Reference

COPYFILTER Function (Record)
Record Data Type


COPYLINKS Function (Record)

COPYLINKS Function (Record)
See Also
CollapseAll image

Copies all the links from a particular record.

COPYLINKS(FromRecord)

Parameters

FromRecord

Type: Record or RecordRef

Specifies the record from which you want to copy links.

Expand image Remarks

Use this function to copy all the links from a specified record and paste the links to the current record.

The link can be a link to a Web site, a file stored on the local or on a remote computer, or a link to a form.

Expand image See Also

Reference

Record Data Type


COUNT Function (Record)

COUNT Function (Record)
See Also Example
CollapseAll image

Counts the number of records in a C/SIDE table.

Number := Record.COUNT

Parameters

Record

Type: Record

Refers to the table to be counted.

Expand image Property Value/Return Value

Type: Integer

The number of records in the table.

Expand image Remarks

This function returns the number of records that meet the conditions of any filters associated with the records. If no filters are set, the function shows the total number of records in the table.

Note Note

The COUNT function does not lock the table before retrieving the number of records in the table. This means that the function reads both uncommitted and committed data, which could cause the number of records that are returned to be inaccurate. To ensure that the count is accurate, use the LOCKTABLE Function (Record) before you use the COUNT function.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType | Subtype
CustomerCount | Integer |
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerCount := CustomerRec.COUNT;
// This statement assigns the number of records in the Customer table
// to the CustomerCount variable. This statement is the same as:
CustomerCount := 0;
IF CustomerRec.FIND('-') THEN
  REPEAT
    CustomerCount := CustomerCount + 1;
  UNTIL CustomerRec.NEXT = 0;

Retrieving the count by using the first statement in the example is much faster because only one command to the Database Management System (DMBS) is needed.

Expand image See Also

Reference

Record Data Type


COUNTAPPROX Function (Record)

COUNTAPPROX Function (Record)
See Also Example
CollapseAll image

Returns an approximate count of the number of records in the table, for example, for updating progress bars or displaying informational messages.

Number := Record.COUNTAPPROX

Parameters

Record

Type: Record

Refers to the table to be counted.

Expand image Property Value/Return Value

Type: Integer

The number of records in the table.

If a filter has been set on the record, this function behaves the same way as the COUNT Function (Record).

Expand image Remarks

The count is approximate because it uses statistical information maintained by SQL Server, which is not kept precisely in synchronization with modifications to the table and is not under transaction control. However, it is much faster to use this information than to perform an accurate record count under transaction control, especially when there are a large number of records in the table.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType | Subtype
FastCount | Integer |
CustomerRec | Record | Customer
CopyCode image Copy Code
FastCount := CustomerRec.COUNTAPPROX

This statement assigns the approximate number of records in the Customer table to the Number variable.

Expand image See Also

Reference

Record Data Type


CURRENTKEY Function (Record)

CURRENTKEY Function (Record)
See Also
CollapseAll image

Returns the current key of a database table.

CurrentKey := Record.CURRENTKEY

Parameters

Record

Type: Record

A record that refers to the table for which you want to find the key that is currently in use.

Expand image Property Value/Return Value

Type: Text or code

The name of the current key of Record.

Expand image See Also

Reference

Record Data Type


DELETE Function (Record)

DELETE Function (Record)
See Also Example
CollapseAll image

Deletes a record in a C/SIDE table.

[Ok :=] Record.DELETE([RunTrigger])

Parameters

Record

Type: Record

The record to be deleted. The record itself does not change.

RunTrigger

Type: Boolean

This optional parameter specifies whether to run the C/AL code in the OnDelete Trigger.

If this parameter is true, then the code in the OnDelete trigger will be executed. If this parameter is false (default), then the code in the OnDelete trigger will not be executed.

The default value is false.

Expand image Property Value/Return Value

Type: Boolean

true if the record was deleted. false if the record was not deleted because it could not be found in the table or if the user did not have the correct permissions. If the C/AL code terminates, false is returned.

If the record does not exist and you do not include a return value, the function will terminate with a run-time error.

Expand image Remarks

The current key and any filters on the record have no effect on this operation. The record to delete is identified by the values in its primary key.

In a multiuser environment, another application can delete the record from the table after you read the record and before you try to delete it. The Database Management System automatically detects such a situation, which causes the DELETE function to fail with a run-time error.

To prevent this situation, you can lock the table while you are using it with the LOCKTABLE Function (Record).

Expand image Example

These examples show how to use the DELETE function. The first example does not use the return value from the DELETE function. This means that a run-time error occurs if the record to be deleted cannot be found.

The second example shows how you can handle errors using the return value.

These examples require that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
Text constant name | ENU Value
Text000 | The customer has been deleted.
Text001 | The customer could not be found.
CopyCode image Copy Code
// Without using the return value:
CustomerRec."No." := '100';
CustomerRec.DELETE;
// Using the return value:
CustomerRec."No." := '100';
IF CustomerRec.DELETE THEN
  MESSAGE(Text000)
ELSE
  ERROR(Text001);

Expand image See Also

Reference

Record Data Type


DELETEALL Function (Record)

DELETEALL Function (Record)
See Also Example
CollapseAll image

Deletes all records in a C/SIDE table that fall within a specified range.

Record.DELETEALL([RunTrigger])

Parameters

RunTrigger

Type: Boolean

Specifies whether to run the C/AL code in the OnDelete Trigger.

If this parameter is true, then the code in the OnDelete trigger will be executed. If this parameter is false (default), then the code in the OnDelete trigger will not be executed.

The default value is false.

Record

Type: Record

Identifies the table in which the deletion will occur. Only those records selected by the filters set for Record are deleted.

Expand image Example

This example requires that you create a Record variable for the Customer table named CustomerRec.
CopyCode image Copy Code
// This C/AL code:
WHILE CustomerRec.FIND('-') DO
  CustomerRec.DELETE;
// Performs the same operation as:
CustomerRec.DELETEALL;

When RunTrigger is false (the default) the DELETEALL function in this example is much faster than the DELETE function because it requires only one call to the server, while the first method requires multiple calls. If RunTrigger is true, there will not be any gain in performance because each record needs to be loaded to the client anyway, in order to execute the OnDelete trigger.

Expand image See Also

Reference

DELETE Function (Record)
Record Data Type


DELETELINK Function (Record)

DELETELINK Function (Record)
See Also
CollapseAll image

Deletes a link that has been added to a record in a table.

DELETELINK(ID)

Parameters

ID

Type: Integer

The ID of the link that you want to delete.

Expand image Remarks

Every time you add a link to a form or a table an entry is created in the Record Link system table. Each entry is given an ID.

Expand image See Also

Reference

Record Data Type


DELETELINKS Function (Record)

DELETELINKS Function (Record)
See Also
CollapseAll image

Deletes all of the links that have been added to a record.

DELETELINKS

Expand image See Also

Reference

DELETELINKS Function (Record)
Record Data Type


FIELDACTIVE Function (Record)

FIELDACTIVE Function (Record)
See Also Example
CollapseAll image

Checks whether a field is enabled.

Ok := Record.FIELDACTIVE(Field)

Parameters

Field

Type: Field

The field that you want to check.

Expand image Property Value/Return Value

Type: Boolean

true if the field is enabled; otherwise, false.

Expand image Remarks

Each field in a record can be set as enabled or disabled in the table description. You cannot use a disabled field because disabled fields cannot contain data.

Expand image Example

This example requires that you create the following variable and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
Text constant name | ENU value
Text000 | Atlanta
Text001 | The field is not marked as enabled.
CopyCode image Copy Code
CustomerRec."Address 2" := Text000;
// If the Address 2 field has not been marked as enbaled, this
// statement causes a run-time error.
// You can avoid this error by performing the following test.
IF CustomerRec.FIELDACTIVE("Address 2") THEN
  CustomerRec."Address 2" := Text000
ELSE
  MESSAGE(Text001);

Expand image See Also

Reference

Record Data Type


FIELDCAPTION Function (Record)

FIELDCAPTION Function (Record)
See Also
CollapseAll image

Returns the current caption of a field as a string.

Caption := Record.FIELDCAPTION(Field)

Parameters

Field

Type: Field

The field for which you want to retrieve the caption.

Expand image Property Value/Return Value

Type: Text or code

The caption is a string.

Expand image Remarks

FIELDCAPTION returns the caption of a field. FIELDCAPTION searches for a CaptionML Property. If none is found, the Name Property will be used. This means that FIELDCAPTION has multilanguage functionality.

Expand image See Also

Reference

TABLECAPTION Function (Record)
CAPTION Function (Form)
Record Data Type

Concepts

Working with Multilanguage Functionality


FIELDERROR Function (Record)

FIELDERROR Function (Record)
See Also Example
CollapseAll image

Stops the execution of the code causing a run-time error, and creates an error message for a field.

Record.FIELDERROR(Field, [Text])

Parameters

Record

Type: Record

The record that contains the field.

Field

Type: Field

The field for which you want to create an error message.

Text

Type: Text or code

Use this optional parameter to include the text of the error message. If you do not use this parameter, default text will be used as shown in the following examples. You can use backslashes (\) to break lines.

Expand image Remarks

Like a run-time error, this function causes the system to automatically abort any transaction.

Expand image Programming Guidelines

We recommend the following guidelines for error messages:

  • Describe what is wrong and how to solve the problem.

  • Write a short descriptive message. Do not use more words than necessary.

  • Note that a period is automatically inserted at the end of a FIELDERROR.

  • Use a text constant for the Text parameter.

For more information, see Progress Windows, MESSAGE, ERROR and CONFIRM Functions.

Expand image Example

In the first example, there is no Text parameter and the field does not have a value. This example requires that you create a Record variable for the Customer table named CustomerRec.
CopyCode image Copy Code
CustomerRec."No." := '';
CustomerRec.FIELDERROR("No.");

The following message is displayed:

You must specify No. in Customer No.=''.

In the next example, there is no Text parameter and the field has a value. This example requires that you create a Record variable for the Customer table named CustomerRec.
CopyCode image Copy Code
CustomerRec."No." := 'NEW 3500';
CustomerRec.FIELDERROR("No.");

The following message is displayed:

No. must not be NEW 3500 in Customer No.='NEW 3500'.

The third example uses a non-empty string as the Text parameter. This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
Text constant name | ConstValue
Text001 | is not valid
CopyCode image Copy Code
CustomerRec."No." := 'NEW 3500';
CustomerRec.FIELDERROR("No.", Text001);

The following message is displayed:

No. is not valid in Customer No.='NEW 3500'.

Expand image See Also

Reference

Record Data Type


FIELDNAME Function (Record)

FIELDNAME Function (Record)
See Also Example
CollapseAll image

Returns the name of a field as a string.

Name := Record.FIELDNAME(Field)

Parameters

Record

Type: Record

The name of the record that contains the field.

Field

Type: Field

The name of the field in the record.

Expand image Property Value/Return Value

Type: Text constant or code

The name of the field specified.

Expand image Remarks

The FIELDCAPTION Function (Record) retrieves the Caption Property of a field. If you want to enable your application for multilanguage functionality now or in the future, you must use the FIELDCAPTION function instead of the FIELDNAME function.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType | Subtype | Length
NameOfField | Text |  | 64
CustomerRec | Record | Customer |
CopyCode image Copy Code
NameOfField := CustomerRec.FIELDNAME("No.");

The name of the field is stored in a string.

The advantage of using this statement instead of Name := 'No.'; is that using the FIELDNAME function dynamically adapts to any change to the field name made in the development system. The statement Name := 'No.'; performs a static assignment.

Expand image See Also

Reference

Record Data Type

Concepts

Working with Multilanguage Functionality


FIELDNO Function (Record)

FIELDNO Function (Record)
See Also Example
CollapseAll image

Returns the number assigned to a field in the table description.

Number := Record.FIELDNO(Field)

Parameters

Record

Type: Record

The name of the record that contains the field.

Field

Type: Field

The name of the field in the record.

Expand image Property Value/Return Value

Type: Integer

The number of the field specified.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType | Subtype
Num | Integer |
CustomerRec | Record | Customer
CopyCode image Copy Code
Num := CustomerRec.FIELDNO("No.");

This statement assigns the number of the No. field in the Customer record to the number variable.

In this example, the FIELDNO function is used to determine which field that a variable, which contains a field number, points to in a record. This example requires that you create the following variables.

Variable name | DataType | Subtype
CurrentFieldNo | Integer |
CustomerRec | Record | Customer
CopyCode image Copy Code
CASE CurrentFieldNo OF
  Customer.FIELDNO("No."):
    ...
  Customer.FIELDNO(Name):
    ...
  Customer.FIELDNO(Address):
    ...
  ELSE
    ...
END;

This construct allows you to take actions based on the field number contained in the CurrentFieldNo variable.

Expand image See Also

Reference

Record Data Type


FILTERGROUP Function (Record)

FILTERGROUP Function (Record)
See Also
CollapseAll image

Changes the filter group that is being applied to the table. You can also use this function to return the number of the current filtergroup. You cannot return the number of the filtergroup and set a new filtergroup at the same time.

[CurrGroup] := Record.FILTERGROUP([NewGroup])

Parameters

Record

Type: Record

A record pointing to the table with which you want to work.

NewGroup

Type: Integer

The number of the filter group that you want to use.

Expand image Property Value/Return Value

Type: Integer

The number of the current filter group.

Expand image Remarks

There are filtergroups with numbers from 0 to 255.

A filtergroup can contain a filter for a Record that has been set earlier with the SETFILTER Function (Record) or the SETRANGE Function (Record). The total filter applied is the combination of all the filters set in all the filtergroups.

When you select a FILTERGROUP, subsequent filter settings by the SETFILTER Function (Record) or the SETRANGE Function (Record) apply to that group.

All groups are active at all times. The only way to disable a group is to remove the filters set in that group.

Filters in different groups are all effective simultaneously. For example, if in one group, a filter is set on customer numbers 1000 to 2000, while in another group, a filter is set on customer numbers 1800 to 3000, the result will be that only numbers in the range 1800 to 2000 are visible.

C/SIDE uses the following FILTERGROUPS internally.

Number Name Description

0

Std

The default group where filters are placed when no other group has been selected explicitly. This group is used for filters that can be set from the filter dialogs by the end user.

1

Global

Used for filters that apply globally to the entire application.

2

Form

Used for the filtering actions that result from the following:

  • SETTABLEVIEW Function (Dataport, Form, Report, XMLport)

  • SourceTableView Property

  • DataItemTableView Property.

3

Exec

Used for the filtering actions that result from the following:

  • SubFormView Property

  • RunFormView Property

4

Link

Used for the filtering actions that result from the following:

  • DataItemLink Property

  • SubFormLink Property

5

Temp

Not currently used.

6

Security

Used for applying security filters for user permissions.

A filter set in a group different from FILTERGROUP 0 cannot be changed by a user that uses a filter dialog to set a filter. If, for example, a filter has been set on customer numbers 1000 to 2000 in group 4, the user can set a filter that delimits this selection further, but cannot widen it to include customer numbers outside the range 1000 to 2000.

It is possible to use one of the internally used groups from C/AL. If you do this, keep in mind that you will replace the filter that C/SIDE assumes is in this group. If, for example, you use FILTERGROUP 4 in a form, you will replace the filtering that is actually the result of applying the SubFormLink Property. This could seriously alter the way forms and subforms interact.

Expand image See Also

Reference

Record Data Type


FIND Function (Record)

FIND Function (Record)
See Also Example
CollapseAll image

Finds a record in a C/SIDE table based on the values stored in keys.

Ok := Record.FIND([Which])

Parameters

Record

Type: Record

On input, Record identifies the record that you want to find. On output, the following possibilities exist:

  • If the record was found, then the record is returned in the Record parameter and any FlowFields in the record are set to zero. You must update the FlowFields using the CALCFIELDS Function (Record).

  • If the record was not found and if you omitted the return value, a run-time error occurs.

Which

Type: Text or code

Specifies how to perform the search. The table is searched until either a record is found or there are no more records. Each character in this string can be present only once. You can combine the '=', '<', and '>' characters. You can use the following characters:

  • = to search for a record that equals the key values (default)

  • > to search for a record that is larger than the key values

  • < to search for a record that is less than the key values

  • + to search for the last record in the table (+ can only be used alone)

  • - to search for the first record in the table (- can only be used alone)

If this parameter contains '=', '>' or '<', then you must assign value to all fields of the current and primary keys before you call FIND.

Expand image Property Value/Return Value

Type: Boolean

true if the record was found; otherwise, false.

If you omit this optional return value and if the record cannot be found, a run-time error occurs. If you include a return value, you must handle any errors.

Expand image Remarks

FIND retrieves the first record that meets the conditions set by Which and the filters associated with Record. The search path reflects the sort order defined by the current key. If the current key is not the primary key, several records might have the same values in current key fields. If this happens, the sort order defined by the primary key as the search path is used.

For more information about the performance differences between using FINDSET and FIND('-'), see C/AL Database Functions and Performance on SQL Server.

Expand image Example

This example requires that you create the following variables an text constants in the C/AL Globals window.

Variable name | Datatype | Subtype
MyDialog | Dialog |
CustomerRec | Record | Customer
Text constant | ENU value
Text000 | The customer was found.\
Text001 | Customer No. %1 is:\%2
Text002 | Sorry, that customer could not be found.
CopyCode image Copy Code
MyDialog.OPEN('Search for customer number...\'
  + '#1##################');
MyDialog.INPUT(1, CustomerRec."No.");
IF CustomerRec.FIND THEN
  MESSAGE(Text000 + Text001, CustomerRec."No.", CustomerRec.Name)
ELSE
  MESSAGE(Text002);

First, you are prompted to enter a customer number to search for.

Search for customer number…

If the number you enter does not exist, the following message is displayed:

Sorry, that customer could not be found.

If the number is found in the Customer table, a message similar to the following is displayed:

The customer was found.

Customer number 01445544 is:

Progressive Home Furnishings

Expand image See Also

Reference

Record Data Type


FINDFIRST Function (Record)

FINDFIRST Function (Record)
See Also Example
CollapseAll image

Finds the first record in a table based on the current key and filter.

[Ok :=] Record.FINDFIRST

Parameters

Record

Type: Record

If the record was found, it is returned in this parameter and any FlowFields in the record are set to zero. You must update the FlowFields by using the CALCFIELDS Function (Record).

If the record was not found and if you omitted the return value, a run-time error occurs.

Expand image Property Value/Return Value

Type: Boolean

true if the record was found; otherwise, false.

If you omit this optional return value and the record cannot be found, a run-time error occurs. If you include a return value, you must handle any errors.

Expand image Remarks

This function should be used instead of FIND('-') when you only need the first record.

You should only use this function when you explicitly want to find the first record in a table or set. Do not use this function in combination with REPEAT..UNTIL.

Expand image Example

This example requires that you create the following variable.

Variable name | Datatype | Subtype
SalesSetupRec | Record | Sales & Receivables Setup

This example also assumes that you have a ConfigurePost function.
CopyCode image Copy Code
// Read the first record only.
IF SalesSetupRec.FINDFIRST THEN BEGIN
  ConfigurePost(SalesSetupRec);
END;

Expand image See Also

Reference

FIND Function (Record)
FINDLAST Function (Record)
FINDSET Function (Record)
Record Data Type


FINDLAST Function (Record)

FINDLAST Function (Record)
See Also Example
CollapseAll image

Finds the last record in a table based on the current key and filter.

[Ok :=] Record.FINDLAST

Parameters

Record

Type: Record

If the record was found, it is returned in this parameter and any FlowFields in the record are set to zero. You must update the FlowFields by using the CALCFIELDS Function (Record).

If the record was not found and if you omitted the return value, a run-time error occurs.

Expand image Property Value/Return Value

Type: Boolean

true if the record was found; otherwise, false.

If you omit this optional return value and the record cannot be found, a run-time error occurs. If you include a return value, you must handle any errors.

Expand image Remarks

This function should be used instead of FIND('+') when you only need the last record.

You should only use this function when you explicitly want to find the last record in a table/set. Do not use this function in combination with REPEAT..UNTIL.

Expand image Example

This example requires that you create a Record variable named GLEntryRec for the G/L Entry table.
CopyCode image Copy Code
// Read the last record only.
IF GLEntryRec.FINDLAST THEN
  …

Expand image See Also

Reference

FIND Function (Record)
FINDFIRST Function (Record)
FINDSET Function (Record)
Record Data Type


FINDSET Function (Record)

FINDSET Function (Record)
See Also Example
CollapseAll image

Finds a set of records in a table based on the current key and filter.

[Ok :=] Record.FINDSET([ForUpdate][, UpdateKey])

Parameters

Record

Type: Record

If the record is found, then the record is returned in this parameter and any FlowFields in the record are set to zero. You must update the FlowFields by using the CALCFIELDS Function (Record).

ForUpdate

Type: Boolean

Set this parameter to true if you want to modify any records in the set; otherwise, set the parameter to false.

If you set this parameter to true, then the LOCKTABLE Function (Record) is immediately run on the table before the records are read.

UpdateKey

Type: Boolean

Set this parameter to true if you want to modify any field value within the current key.

This parameter only applies if the ForUpdate parameter is true.

Expand image Property Value/Return Value

Type: Boolean

true if the record set was found; otherwise, false.

If you omit this optional return value and if the record cannot be found, then a run-time error occurs. If you include a return value, then you must handle any errors.

Expand image Remarks

FINDSET can only retrieve records in ascending order. If you want to loop from the bottom up, then you should use FIND('+').

You should use this function only when you explicitly want to loop through a recordset. You should only use this function in combination with REPEAT..UNTIL.

The following table describes the general rules for using FINDSET.

Usage | Rule
FINDSET(FALSE,FALSE) | Read-only. This uses no server cursors, and the recordset is read with a single server call.
FINDSET(TRUE,FALSE) | This is used to update non-key fields. This uses a cursor with a fetch buffer that is similar to FIND('-').
FINDSET(TRUE,TRUE) | This is used to update key fields.

This function is designed to optimize finding and updating sets. If you set any or both of the parameters to false, then you can still modify the records in the set, but these updates will not be performed optimally.

For more information about performance differences between using FINDSET and FIND('-'), see C/AL Database Functions and Performance on SQL Server.

Expand image Example

This example shows how to use the FINDSET function to loop through a set without updating it. This example requires that you create a Record variable named SalesLine for the Sales Line table and that you have a CopyLine function.
CopyCode image Copy Code
SalesLine.SETFILTER("Purch. Order Line No.",'<>0');
IF SalesLine.FINDSET THEN BEGIN
  REPEAT
    CopyLine(SalesLine);
  UNTIL SalesLine.NEXT = 0;
END;

This example shows how to use the FINDSET function to loop through a set and update a field that is not within the current key. This example requires that you create the following variables.

Variable name | Data type | Subtype
SalesLine | Record | Sales Line
DocumentType | Option |
DocumentNo | Code |

This example assumes that you have assigned values to the DocumentType and DocumentNo variables and that you have a GetNewLocation function, which returns a value that is a Code data type.
CopyCode image Copy Code
SalesLine.SETRANGE("Document Type",DocumentType);
SalesLine.SETRANGE("Document No.",DocumentNo);
IF SalesLine.FINDSET(TRUE, FALSE) THEN BEGIN
  REPEAT
    SalesLine."Location Code" := GetNewLocation(SalesLine);
    SalesLine.MODIFY;
  UNTIL SalesLine.NEXT = 0;
END;

This example shows how to use the FINDSET function to loop through a set and update a field that is within the current key. This example requires that you create the following variables.

Variable name | DataType | Subtype
SalesShptLine | Record | Sales Shipment Line
SalesLine | Record | Sales Line
CopyCode image Copy Code
SalesShptLine.SETRANGE("Order No.",SalesLine."Document No.");
SalesShptLine.SETRANGE("Order Line No.",SalesLine."Line No.");
SalesShptLine.SETCURRENTKEY("Order No.","Order Line No.");
IF SalesShptLine.FINDSET(TRUE, TRUE) THEN BEGIN
  REPEAT
    SalesShptLine."Order Line No." := SalesShptLine."Order Line No." + 10000;
    SalesShptLine.MODIFY;
  UNTIL SalesShptLine.NEXT = 0;
END;

Expand image See Also

Reference

FIND Function (Record)
FINDFIRST Function (Record)
FINDLAST Function (Record)
Record Data Type


GET Function (Record)

GET Function (Record)
See Also Example
CollapseAll image

Finds a record based on values stored in primary key fields.

[Ok :=] Record.GET([Value] ,...)

Parameters

Record

Type: Record

The record in the table.

Value,…

Type: any

Values in primary key fields. The data type of this parameter must match the data type of the corresponding primary key field. For example, if you enter an integer, the data type of the corresponding primary key field must also be an integer. The value 0 (zero) or an empty string is assigned to unspecified fields.

Expand image Property Value/Return Value

Type: Boolean

true if the record was found; otherwise, false.

If you omit this optional return value and if the record cannot be found, a run-time error occurs. If you include the return value, you must handle any errors.

Expand image Remarks

This function always uses the primary key for the table and ignores any filters. The current key and filters are not changed after you call this function.

Expand image Example

This example requires that you create the following variable and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
Text constant | ENU value
Text000 | The record was found.
Text001 | The record could not be found.
CopyCode image Copy Code
CustomerRec.GET('1120');
// This statement causes a run-time error if customer 1120 cannot be
// found. To avoid this, use the following construct:
IF CustomerRec.GET('1120') THEN
  MESSAGE(Text000)
ELSE
  MESSAGE(Text001);

Expand image See Also

Reference

Record Data Type


GETFILTER Function (Record)

GETFILTER Function (Record)
See Also Example
CollapseAll image

Returns a list of the filters within the current filter group that are applied to a field.

String := Record.GETFILTER(Field)

Parameters

Record

Type: Record

The input record.

Field

Type: Field

The input field.

Expand image Property Value/Return Value

Type: Text constant or code

This string contains a list of the filters applied to the field in the record.

Expand image Example

This example shows how to use the GETFILTER function.

This example requires that you create the following Global variables in the C/AL Globals window.

Variable name | Data type | Subtype
String | Text |
CustomerEntry | Record | Cust. Ledger Entry

This example requires that you create the following text constant in the C/AL Globals window.

Text constant | ENU value
Text000 | 'The filter is:\%1'
CopyCode image Copy Code
// Write the following code in the OnRun trigger.
CustomerEntry.SETRANGE(Amount, -100, 100);
String := CustomerEntry.GETFILTER(Amount);
MESSAGE(Text000, String);

The following message is displayed:

The filter is:

-100..100

Expand image See Also

Reference

GETFILTERS Function (Record)
SETFILTER Function (Record)
SETRANGE Function (Record)
Record Data Type


GETFILTERS Function (Record)

GETFILTERS Function (Record)
See Also Example
CollapseAll image

Returns a string which contains a list of the filters within the current filter group for all fields in a record. In addition, this function also returns the state of the MARKEDONLY Function (Record).

String := Record.GETFILTERS

Parameters

Record

Type: Record

The record from which you want a list of filters.

Expand image Property Value/Return Value

Type: Text or code

This string contains a list of the filters for all fields in Record.

Expand image Example

This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Subtype | Length
Str | Text |  | 1024
CustLedgerEntry | Record | Cust. Ledger Entry |
Text constant | ENU value
Text000 | The filters are:\
CopyCode image Copy Code
CustLedgerEntry.SETRANGE(Amount, -100, 100);
CustLedgerEntry.SETRANGE("Posting Date", 010108D, 123108D);
Str := CustLedgerEntry.GETFILTERS;
MESSAGE(Text000 + '%1', Str);

On a computer with the regional format set to English (United States), the message window displays the following:

The filters are:

Posting Date: 01/01/08..12/31/08, Amount: -100..100

Expand image See Also

Reference

GETFILTER Function (Record)
SETFILTER Function (Record)
SETRANGE Function (Record)
Record Data Type


GETPOSITION Function (Record)

GETPOSITION Function (Record)
See Also
CollapseAll image

Returns a string that contains the primary key of the current record.

String := Record.GETPOSITION([UseNames])

Parameters

UseNames

Type: Boolean

Expand image Property Value/Return Value

Type: Text or code

The string has the same format as the SourceTableRecord Property on a form.

Expand image Remarks

The UseNames parameter is optional. If it is set to true (default value) or if it is empty, the returned string contains references to field names in the table with which the record is associated. If the parameter is set to false, field numbers are used instead.

Expand image See Also

Reference

Record Data Type


GETRANGEMAX Function (Record)

GETRANGEMAX Function (Record)
See Also Example
CollapseAll image

Returns the maximum value in a range for a field.

Value := Record.GETRANGEMAX(Field)

Parameters

Record

Type: Record

The record that contains the field.

Field

Type: Field

The field for which you want to find the maximum value. The current filter on Field must be a single range filter; otherwise, a run-time error occurs.

Expand image Property Value/Return Value

Type: Depends on Field

Contains the maximum value of the range set for Field. The type of the return value must match the type of Field.

Expand image Example

In this example, you have a filter that defines a single range.

This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Subtype | Length
CustomerRec | Record | Customer |
Val | Code |  | 10
Text constant | ENU value
Text000 | The maximum value is: %1.
CopyCode image Copy Code
CustomerRec.SETFILTER("No.",'100..200');
Val := CustomerRec.GETRANGEMAX("No.");
MESSAGE(Text000, Val);

The following message is displayed:

The maximum value is: 200.

In this example, you have a filter that is a single value.

This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Subtype | Length
CustomerRec | Record | Customer |
Val | Code |  | 10
Text constant | ENU value
Text000 | The maximum value is: %1.
CopyCode image Copy Code
CustomerRec.SETFILTER("No.",'100');
Val := CustomerRec.GETRANGEMAX("No.");
MESSAGE(Text000, Val);

The following message is displayed:

The maximum value is: 100.

In this example, you have a filter that is not a single range.

This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Subtype | Length
CustomerRec | Record | Customer |
Val | Code |  | 10
Text constant | ENU value
Text000 | The maximum value is: %1.
CopyCode image Copy Code
CustomerRec.SETFILTER("No.",'200|300');
Val := CustomerRec.GETRANGEMAX("No.");
MESSAGE(Text000, Val);

This example causes a run-time error to occur.

Expand image See Also

Reference

GETRANGEMIN Function (Record)
Record Data Type


GETRANGEMIN Function (Record)

GETRANGEMIN Function (Record)
See Also Example
CollapseAll image

Returns the minimum value in a range for a field.

Value := Record.GETRANGEMIN(Field)

Parameters

Record

Type: Record

The record that contains the field.

Field

Type: Field

The field for which you want to find the minimum value. The current filter on Field must be a single range filter; otherwise, a run-time error occurs.

Expand image Property Value/Return Value

Type: Depends on Field

Contains the minimum value of the range set for Field. The type of the return value must match the type of Field.

Expand image Example

In this example, you have a filter that defines a single range.

This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Subtype | Length
CustomerRec | Record | Customer |
Val | Code |  | 10
Text constant | ENU value
Text000 | The minimum value is: %1.
CopyCode image Copy Code
CustomerRec.SETFILTER("No.",'100..200');
Val := CustomerRec.GETRANGEMIN("No.");
MESSAGE(Text000, Val);

The following message is displayed:

The minimum value is: 100.

In this example, you have a filter that is a single value.

This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Subtype | Length
CustomerRec | Record | Customer |
Val | Code |  | 10
Text constant | ENU value
Text000 | The minimum value is: %1.
CopyCode image Copy Code
CustomerRec.SETFILTER("No.",'100');
Val := CustomerRec.GETRANGEMIN("No.");
MESSAGE(Text000, Val);

The following message is displayed:

The minimum value is: 100.

In this example, you have a filter which is not a single range.

This example requires that you create the following variables and text constant in the C/AL Globals window.

Variable name | DataType | Subtype | Length
CustomerRec | Record | Customer |
Val | Code |  | 10
Text constant | ENU value
Text000 | The minimum value is: %1.
CopyCode image Copy Code
CustomerRec.SETFILTER("No.",'200|300');
Val := CustomerRec.GETRANGEMIN("No.");
MESSAGE(Text000, Val);

This example causes a run-time error to occur.

Expand image See Also

Reference

GETRANGEMAX Function (Record)
Record Data Type


GETVIEW Function (Record)

GETVIEW Function (Record)
See Also
CollapseAll image

Returns a string that describes the current sort order, key, and filters on a table.

String := Record.GETVIEW([UseNames])

Parameters

UseNames

Type: Boolean

This parameter is optional. If this parameter is true (default value) or if it is empty, then the returned string contains references to field captions in the table with which the record is associated. If this parameter is false, the returned string contains references to field numbers.

Expand image Property Value/Return Value

Type: Text or code

The string format is the same as the SourceTableView Property on forms.

Expand image Remarks

If the SETVIEW Function (Record) has been executed, then the function will return the value set by SETVIEW.

Expand image See Also

Reference

Record Data Type


HASFILTER Function (Record)

HASFILTER Function (Record)
See Also
CollapseAll image

Determines if a filter is attached to a record within the current filter group.

Ok := Record.HASFILTER

Parameters

Record

Type: Record

The record that you want to check.

Expand image Property Value/Return Value

Type: Boolean

true if there is a filter; otherwise, false.

Expand image See Also

Reference

Record Data Type


HASLINKS Function (Record)

HASLINKS Function (Record)
See Also
CollapseAll image

Determines if a record contains any links.

Ok := HASLINKS

Expand image Property Value/Return Value

Type: Boolean

true if the record contains at least one link; otherwise, false.

Expand image Remarks

The link can be a link to a Web site, a file stored on the local or on a remote computer, or a link to a Microsoft Dynamics NAV form.

Expand image See Also

Reference

Record Data Type


INIT Function (Record)

INIT Function (Record)
See Also Example
CollapseAll image

Initializes a record in a C/SIDE table.

Record.INIT

Parameters

Record

Type: Record

The record that you want to initialize.

Expand image Remarks

This function assigns default values to each field in the record. The values that are assigned in the record correspond to those defined when the table was created. If no value was assigned when the table was created, the values are assigned based on the data type, as shown in the following table.

Data type | Default value
BigInteger | 0
BigText | <Empty>
Binary | <Empty>
BLOB | <Empty>
Boolean | No
Code | '' (empty string)
Date | 0d (Undefined date)
DateFormula | '' (empty string)
DateTime | 0DT (Undefined datetime)
Decimal | 0.0
Duration | 0
GUID | 00000000-0000-0000-0000-000000000000
Integer | 0
Option | 0
RecordID | <Empty>
TableFilter | <Empty>
Text | '' (empty string)
Time | 0T (Undefined time)

Primary key and timestamp fields are not initialized.

After the function executes, you can change the values in any or all of the fields before you call the INSERT Function (Record) to enter the record in the table. Be sure that the fields that make up the primary key contain values that make the total primary key unique. If the primary key is not unique (such as the record already exists), then the record is rejected.

Expand image Example

In this example, assume that the primary key includes the "No." field. This example requires that you create a Record variable named CustomerRec for the Customer table.
CopyCode image Copy Code
// Scenario 1
CustomerRec.INIT;
CustomerRec."No." := '1120';
CustomerRec.INSERT;
// Scenario 2
CustomerRec."No." := '1120';
CustomerRec.INIT;
CustomerRec.INSERT;

Since INIT does not initialize the primary key fields, the order of the statements in this example is not important. Scenario 1 causes the same result as scenario 2.

Expand image See Also

Reference

Record Data Type


INSERT Function (Record)

INSERT Function (Record)
See Also Example
CollapseAll image

Inserts a record into a C/SIDE table.

[Ok :=] Record.INSERT([RunTrigger])

Parameters

Record

Type: Record

The record that you want to insert.

RunTrigger

Type: Boolean

If this parameter is true, the code in the OnInsert Trigger is executed. If this parameter is false, the code in the OnInsert trigger is not executed. The default value is false.

Expand image Property Value/Return Value

Type: Boolean

true if the record was inserted; otherwise, false.

If you omit this optional return value and if the record cannot be inserted, a run-time error occurs. If you include the return value, you must handle any errors.

Expand image Remarks

Records are uniquely identified by the values in primary key fields. The C/SIDE Database Management System (DBMS) checks the primary key for the table before it inserts a new record.

If the table contains an auto-increment field, the auto-increment feature is used if the record contains a zero value in that field. The auto-increment feature enters the new value into the field as part of the insert.

If the auto-increment field contains a non-zero value, that value is inserted into the table and the auto-increment feature is not used. If the value in the auto-increment field is greater than the last auto-increment value in the table, the next auto-increment value that is entered into the table will be greater than the value in the field that you just inserted. If the value in the auto-increment field already exists in the table, a run-time error occurs.

Expand image Example

This example shows how to use the INSERT function without a return value.

CopyCode image Copy Code
Customer.INIT
Customer."No." := '1120';
Customer.INSERT;

If customer 1120 already exists, a run-time error occurs.

This example requires that you create the following variable and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
Text constant name | ENU value
Text000 | Customer no: %1 inserted.
Text001 | Customer no: %1 already exists.
CopyCode image Copy Code
CustomerRec.INIT
CustomerRec."No." := '1120';
If CustomerRec.INSERT THEN
  MESSAGE(Text000, CustomerRec."No.")
ELSE
  MESSAGE(Text001, CustomerRec."No.");

No run-time error occurs if customer 1120 already exists.

Expand image See Also

Reference

Record Data Type


ISEMPTY Function (Record)

ISEMPTY Function (Record)
See Also
CollapseAll image

Determines if a C/SIDE table or a filtered set of records is empty.

Empty := Record.ISEMPTY

Parameters

Record

Type: Record

Refers to the table of the filtered set of records that you want to check.

Expand image Property Value/Return Value

Type: Boolean

Expand image Remarks

This function determines whether the table is empty. If you have applied filters, the function determines whether the filtered set of records is empty.

The number of filters that you have applied to the records affects the speed of the ISEMPTY function. The fewer the number of filters, the faster the operation is performed.

When you are using SQL Server, this function is faster than using the COUNT Function (Record) and then testing the result for zero.

Expand image See Also

Reference

Record Data Type


LOCKTABLE Function (Record)

LOCKTABLE Function (Record)
See Also Example
CollapseAll image

Locks a C/SIDE table to protect it from write transactions that conflict with each other.

Record.LOCKTABLE([Wait] [, VersionCheck])

Parameters

Record

Type: Record

The record that refers to the table that you want to lock.

Wait

Type: Boolean

Specifies what to do if the table is already locked.

If this parameter is true and if another application has already locked the table, the system will wait until the table is unlocked.

If this parameter is false and if another application has already locked the table, a run-time error occurs.

VersionCheck

Type: Boolean

If this parameter is true, the version will be checked. If this parameter is false, blank, or not used, the version will not be checked.

Expand image Remarks

Because all write operations automatically lock the table in use, LOCKTABLE would appear unnecessary. However, you could have a transaction in which an application wants to inspect data and then only possibly change it, with a guarantee that the data being changed has not been modified by other applications since the read operation. The solution is to explicitly lock the table before the read operation. This ensures that no other application makes changes between the read operation and the possible write operation.

The SQL Server Option for Microsoft Dynamics NAV only supports the default values for the parameters of the LOCKTABLE function – LOCKTABLE(TRUE,FALSE). From the point where it takes effect, the LOCKTABLE function causes all operations on the table to be SERIALIZABLE. If [Wait] is set to false, it will be ignored. You must set [VersionCheck] to false otherwise an error will occur.

Expand image Example

This example shows how to use the LOCKTABLE function without the VersionCheck parameter.

This example uses pseudo-language to show the scope of write locks. Both an explicit lock and an automatic lock are illustrated.

The first line (1) explicitly locks table A. If this explicit lock was not set on table A, the Database Management System (DBMS) would automatically lock this table when a record was inserted (3). Table B is not locked explicitly, but is locked automatically by the DBMS when a record is inserted (4). Both locks are active until the system exits the C/AL code module (5).
CopyCode image Copy Code
BeginWriteTransaction
LockTable(TableA) // (1)
FindRec(TableA, ...) // (2)
.
.
InsertRec(TableA,...) // (3)
.
InsertRec(TableB) // (4)
.
.
EndWriteTransaction // (5)

This example shows how to use the LOCKTABLE function with the VersionCheck parameter.

If a data update depends on a prior read operation and there is a long time between the read operation and the write operation, you may not want to lock the table as you usually would during a transaction. This enables you to avoid preventing other users from updating the table until your transaction is committed. You can do this by using the VersionCheck parameter, which compares time stamps to check if a record has been changed.
CopyCode image Copy Code
Customer.GET('AAA 1050'); // Reading at 10:00.
// Time stamp automatically set to 10:00
.
.
.
Customer.LOCKTABLE(TRUE, TRUE); // Start write transaction at 10:15
.
.
.
Customer.MODIFY
. // A run-time error occurs if the time stamp on Customer in the data
. // version used in the transaction differs from the time stamp made
. // the last time you read the record before the write transaction
. // started.
{End write transaction}

When the VersionCheck parameter is true, the MODIFY Function (Record) compares the time stamp of the record that you modify within a transaction with the time stamp made the last time you read the record before the transaction started. If these time stamps differ, the record was changed after you read it and before you locked the table. If this occurs, an error message is displayed.

Expand image See Also

Reference

Record Data Type


MARK Function (Record)

MARK Function (Record)
See Also Example
CollapseAll image

Marks a record. You can also use this function to determine if a record is marked.

[IsMarked :=] Record.MARK([SetMarked])

Parameters

Record

Type: Record

The input record.

SetMarked

Type: Boolean

If this parameter is true, the function will mark the record. (Previously marked records remain marked.)

If this parameter is false, the function will remove any mark.

Expand image Property Value/Return Value

Type: Boolean

true if the record is marked; otherwise, false.

The mark is effective until the application stops executing.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image Example

This example shows how to use the MARK function. Assume that initially no records are marked.

This example requires that you create the following text constant in the C/AL Globals window.

Text constant | ENU value
Text000 | 'Customer.No.: %1, Marked?: %2'
CopyCode image Copy Code
Customer.SETCURRENTKEY("No.");
Customer."No." := 'NEW 3500';
Customer.FIND('=');
Customer.MARK(TRUE); // Mark a record.
Customer.FIND('-'); // Find first record.
REPEAT // Go through records
Marked := Customer.MARK; // Test if marked.
MESSAGE(Text000, Customer."No.", Marked);
UNTIL Customer.NEXT = 0;

The message windows could show the following:

Customer No.: AAA 1050, Marked?: No

Customer No.: DEL 3500, Marked?: No

Customer No.: NEW 3500, Marked?: Yes

Customer No.: PEA 2500, Marked?: No

Customer No.: SOP 7500, Marked?: No

This example shows how to use the MARK function with the MARKEDONLY function. Assume that initially no records are marked.

This example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text001 | 'Number of records before MARKEDONLY: %1\'
Text002 | 'Number of records after MARKEDONLY: %2'
CopyCode image Copy Code
SETCURRENTKEY(Customer."No.");
Customer."No." := 'NEW 3500';
FIND(Customer, '=');
MARK(Customer, TRUE); //Mark a record.
No1 := COUNT(Customer);
MARKEDONLY(Customer, TRUE);
No2 := COUNT(Customer);
MESSAGE(Text001 + Text002, No1, No2);

The message windows could show the following:

Number of records before MARKEDONLY: 5

Number of records after MARKEDONLY: 1

Expand image See Also

Reference

MARKEDONLY Function (Record)
Record Data Type


MARKEDONLY Function (Record)

MARKEDONLY Function (Record)
See Also Example
CollapseAll image

Activates a special filter. After you use this function, your view of the table only includes records marked by this function.

[IsMarkedOnly :=] Record.MARKEDONLY([SetMarkedOnly])

Parameters

Record

Type: Record

A record from the table for which you want to activate the special 'mark' filter.

SetMarkedOnly

Type: Boolean

Changes the state of the special filter. This parameter is optional.

If this parameter if true, only marked records are included. If this parameter is false, all records are included.

Expand image Property Value/Return Value

Type: Boolean

true if the special filter is in use; otherwise, false.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image Example

This example shows how to use MARK and MARKEDONLY. Assume that initially none of the records are marked.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
No1 | Integer |
No2 | Integer |
Text constant | ENU value
Text000 | Number of records before MARKEDONLY: %1.\
Text001 | Number of records after MARKEDONLY: %2.
CopyCode image Copy Code
CustomerRec.SETCURRENTKEY("No.");
CustomerRec."No." := '10000';
CustomerRec.FIND('=');
CustomerRec.MARK(TRUE); // Mark a record.

No1 := CustomerRec.COUNT;
CustomerRec.MARKEDONLY(TRUE);
No2 := CustomerRec.COUNT;
MESSAGE(Text000 + Text001, No1, No2);

The following messages could be displayed:

Number of records before MARKEDONLY: 68.

Number of records after MARKEDONLY: 1.

Expand image See Also

Reference

MARK Function (Record)
Record Data Type


MODIFY Function (Record)

MODIFY Function (Record)
See Also
CollapseAll image

Modifies a record in a C/SIDE table.

[Ok :=] Record.MODIFY([RunTrigger])

Parameters

Record

Type: Record

The record that you want to modify.

RunTrigger

Type: Boolean

Specifies whether to run the C/AL code in the OnModify Trigger.

If this parameter is true, then the code will be executed. If this parameter is false (default), then the code will not be executed.

Expand image Property Value/Return Value

Type: Boolean

true if the record was modified; otherwise, false.

If you omit this optional return value and if the record cannot be found, then a run-time error occurs. If you include the return value, then you must handle any errors.

Expand image Remarks

Select the record that you want to replace by using the primary key fields. The record's current key and filters do not affect the operation.

In multiuser environments, another application could modify the record between the time that you read the record and when you attempt to modify it. The C/SIDE Database Management System (DBMS) automatically watches for this. If a conflict occurs, then it cancels the MODIFY function and displays an error message.

If you are running Microsoft Dynamics NAV with Microsoft SQL Server and if different threads in the code modify a record, then you must refresh the value of the record variable before you edit the record again. Otherwise, you get the following error:

Another user has modified the record for this <Table Name> after you retrieved it from the database.

Enter your changes again in the updated window, or start the interrupted activity again.

You can use the GET Function (Record) to refresh the record variable. Example 2 shows how to do this.

Expand image Example 1

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
No1 | Integer |
No2 | Integer |
Text constant | ENU value
Text000 | The customer no. %1 is:\
Text001 | Now customer no. %1 is:\
CopyCode image Copy Code
// Find customer.
CustomerRec.FIND('-');
// Display name.
MESSAGE(Text000 + '%2', CustomerRec."No.", CustomerRec.Name);
// Modify customer name.
CustomerRec.Name := 'Progressive Home Furnishings';
CustomerRec.MODIFY;
// Display new name.
MESSAGE(Text001 + '%2', CustomerRec."No.", CustomerRec.Name);

Messages that are similar to the following are displayed:

The customer no. AAA 1050 is:

AAA Furniture Manufacturing

Now customer no. AAA 1050 is:

Progressive Home Furnishings

Expand image Example 2

In this example, you create a Line table and a Header table. The Line table has the following fields:

Field | DataType | Length
Code | Code | 10
HeaderCode | Code | 10
Value | Text | 30

The Header table has the following fields.

Field | DataType | Length
Code | Code | 10
Value | Text | 30

The Header table also has a Change function.

First, you insert a record into the Line table. Then, you call a Header table function called Change, which modifies the record in the Line table that you inserted. After the Header.Change function, you must refresh the Line variable before you call any functions that edit this record again, such as MODIFY, MODIFYALL, DELETE, DELETEALL, or RENAME.

This example requires that you create the following variables in the C/AL Globals window.

Variable name | DataType | Subtype
Line | Record | Line
Header | Record | Header
CopyCode image Copy Code
Line.Code := '4';
Line.HeaderCode := 'M';
Line.Value := 'Value 4';
Line.INSERT;

Header.Change

Line.GET(Line.Code); // Refresh the Line variable.
Line.Value := 'New value';
Line.MODIFY(TRUE);

If you omit the Line.GET(Line.Code); statement and you are running Microsoft Dynamics NAV with Microsoft SQL Server, then a run-time error occurs.

Expand image See Also

Reference

MODIFYALL Function (Record)
Record Data Type


MODIFYALL Function (Record)

MODIFYALL Function (Record)
See Also Example
CollapseAll image

Modifies a field in all records within a range that you specify.

Record.MODIFYALL(Field, NewValue [, RunTrigger])

Parameters

Record

Type: Record

The record that contains the field that you want to modify.

Field

Type: Field

The field that you want to modify.

NewValue

Type: Any

The value that you want to assign to Field in all records. The data type of NewValue must match the data type of Field.

RunTrigger

Type: Boolean

If this parameter is true, the code in the OnModify Trigger is executed. If this parameter is false (default), the code in the OnModify trigger is not executed.

Expand image Remarks

If no filter is set, the field is modified in all records in the table. If a filter is set, the fields are modified only in the records which fall within the range specified by the filter.

The OnValidate (Fields) Trigger is never executed when MODIFYALL is used.

Expand image Example

This example requires that you create the following variable in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
// The result of this statement:
CustomerRec.MODIFYALL("Statistics Group", 2);
// is equivalent to:
IF CustomerRec.FIND('-') THEN
  REPEAT
    CustomerRec."Statistics Group" := 2;
    CustomerRec.MODIFY;
  UNTIL CustomerRec.NEXT = 0;

Expand image See Also

Reference

MODIFY Function (Record)
Record Data Type


NEXT Function (Record)

NEXT Function (Record)
See Also Example
CollapseAll image

Steps through a specified number of records and retrieves a record.

Steps := Record.NEXT([Steps])

Parameters

Record

Type: Record

The record from which the search begins.

Steps

Type: Integer

Specifies the direction of the search and how many records to step over. This parameter follows the following rules:

  • >0 Search Steps records forward in the table

  • <0 Search Steps records backwards in the table.

  • =0 No effect

If you do not specify this parameter, the next record is found.

Expand image Property Value/Return Value

Type: Integer

The number of records inspected which meet the criteria of any filters and the current key. This value can be less than Steps, depending on the number of records in the table. If the table is empty, then zero is returned and Record does not change.

Expand image Remarks

This function locates a record positioned a given number of steps forward or backward from Record. Movement through the table is governed by the filters and the current key associated with the records. The fields in Record that will be compared with the current key fields must contain appropriate values before the function is called.

Expand image Example

This example requires that you create the following variables in the C/AL Globals window.

Variable name | DataType | Subtype
Count | Integer |
CustomerRec | Record | Customer
CopyCode image Copy Code
Count := 0;
IF CustomerRec.FIND('-') THEN
  REPEAT
    Count := Count + 1;
  UNTIL CustomerRec.NEXT = 0;

This code uses a REPEAT UNTIL loop to count the number of entries in the Customer table. The FIND function finds the first entry in the table. Each time the NEXT function is called, it steps one record forward. When NEXT equals zero (0), there are no more entries in the table and the loop is exited.

Expand image See Also

Reference

Record Data Type


READCONSISTENCY Function (Record)

READCONSISTENCY Function (Record)
See Also
CollapseAll image

Determines if the table supports read consistency.

Ok := Record.READCONSISTENCY

Parameters

Record

Type: Record

Refers to the table that you want to check for read consistency.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether read consistency is supported.

true if the table supports read consistency; otherwise, false.

Expand image Remarks

The advantage of read consistency is that a snapshot of the data can be used when you do not want the data to change during the transaction. For example, you can print a report and be sure that other users have not updated the report data. Further, this function does not negatively affect the concurrency of the system in a multiuser environment.

The Classic Database Server supports read consistency as an integral part of the database architecture. SQL Server does not support this feature. It implements a consistent snapshot by locking data as it is read to prevent other users from changing it. This significantly reduces concurrency for tables that are frequently accessed by multiple users.

Expand image See Also

Reference

Record Data Type


READPERMISSION Function (Record)

READPERMISSION Function (Record)
See Also
CollapseAll image

Determines if you can read from a table. This function can test for both full read permission and partial read permission that has been granted with a security filter.

Ok := Record.READPERMISSION

Parameters

Record

Type: Record

The record in the table from which you want to read.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether you have permission to read from the table.

true if you can read from some or all of the table. false if you cannot read from the table.

Expand image Remarks

This function uses the filter that is currently applied to the Record to determine whether you have read permission. If no filter is applied, the function tests for full read permission. If a filter has been set, the function only tests for read permission within the range of the filter.

To determine whether the user has a partial read permission, because a security filter has been applied, use the SETPERMISSIONFILTER Function (Record) before testing the permission with READPERMISSION.

If you do not have permission to read from a table and you attempt to read, a run-time error occurs. This function allows you to determine in advance if you have read permission. When the permissions are checked, the combination of permissions in the license file and the user's permissions in the Permission table is considered.

Expand image See Also

Reference

Record Data Type


RECORDLEVELLOCKING Function (Record)

RECORDLEVELLOCKING Function (Record)
See Also
CollapseAll image

Determines whether the table supports record-level locking.

Ok := Record.RECORDLEVELLOCKING

Parameters

Record

Type: Record

Refers to the table that you want to check.

Expand image Property Value/Return Value

Type: Boolean

true if the table supports record-level locking; otherwise, false.

Expand image Remarks

When you are using SQL Server, you can use record-level locking.

When you are using the Microsoft Dynamics NAV Database Server, you cannot use record-level locking.

Expand image See Also

Reference

Record Data Type


RELATION Function (Record)

RELATION Function (Record)
See Also
CollapseAll image

Determines the table relationship of a given field.

TableNumber := Record.RELATION(Field)

Parameters

Record

Type: Record

The record that contains Field.

Field

Type: Rield

The field for which you want to find the table relationship.

Expand image Property Value/Return Value

Type: Integer

The number of the table that has a relationship with Field. This relationship is set up through the properties.

Expand image Remarks

You can use this function for several purposes, such as to determine lookups or to check if you have permission to read from a table.

Expand image See Also

Reference

Record Data Type


RENAME Function (Record)

RENAME Function (Record)
See Also
CollapseAll image

Changes a primary key in a C/SIDE table.

[Ok :=] Record.RENAME(Value1, [Value2],...)

Parameters

Record

Type: Record

The record that contains the primary key that you want to change.

Value1, Value2, …

Type: Text

The new values for the primary key.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether the primary key was renamed. If the record does not exist of if you do not have permission to write to the table, typically false is returned.

Expand image Remarks

An example of a scenario in which you could use the RENAME function is the following: if you use the customer's phone number as the customer number, you can use this function to change the customer number if the phone number changes.

Expand image See Also

Reference

Record Data Type


RESET Function (Record)

RESET Function (Record)
See Also Example
CollapseAll image

Removes all filters, including any special filters set by MARKEDONLY, and changes the current key to the primary key. Also removes any marks on the record and clears any C/AL variables on the record.

Record.RESET

Parameters

Record

Type: Record

The record that you want to reset.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
Count1 | Integer |
Count2 | Integer |
Text constant | ENU value
Text000 | Before RESET: %1.\
Text001 | After RESET: %2.
CopyCode image Copy Code
CustomerRec.SETFILTER("No.", '10000');
CustomerRec.SETRANGE("Salesperson Code", 'PS');
CustomerRec.MARKEDONLY(TRUE);
Count1 := CustomerRec.COUNT; // Count marked customers in the range.
CustomerRec.RESET;
Count2 := CustomerRec.COUNT; // Count all customers.
MESSAGE(Text000 + Text001, Count1, Count2);

Messages similar to the following are displayed:

Before RESET: 0

After RESET: 68

The example shows that RESET removed all filters.

Expand image See Also

Reference

Record Data Type


SETCURRENTKEY Function (Record)

SETCURRENTKEY Function (Record)
See Also
CollapseAll image

Selects a key for a table.

[Ok :=] Record.SETCURRENTKEY(Field1, [Field2],...)

Parameters

Record

Type: Record

The record that contains the fields that identify the key that you want to select.

Field1, Field2, …

Type: Field

One or more fields that identify the key that you want to select.

Expand image Property Value/Return Value

Type: Boolean

true if the key was selected; otherwise, false.

If you omit this optional return value and if the key cannot be found, then a run-time error occurs. If you include a return value, then you must handle any errors.

Expand image Remarks

SETCURRENTKEY is used to select a key for a record and set the sort order that is used for the table in question. This key becomes the current key and is used by the FIND Function (Record), the NEXT Function (Record), and other functions until another key is selected. Until this function is called, the table's primary key is used as the current key.

Use the following guidelines when you use SETCURRENTKEY:

  • Inactive fields are ignored. Only active keys are scanned.

  • When searching for a key, C/SIDE selects the first occurrence of the specified field(s). This means the following:

    • If you specify only one field as a parameter when you call SETCURRENTKEY, then the key that is actually selected may consist of more than one field.

    • If the field that you specify is the first component of several keys, then the key that is selected may not be the key that you expect.

  • If no keys can be found that include the field(s) that you specify, then a run-time error occurs unless you test the Boolean return value of SETCURRENTKEY in your code.

  • If you do test the return value, then you must decide what the program should do if the function returns false, because without a run-time error, the program will continue to run even though no key was found.

  • Use only the necessary key fields in a call of SETCURRENTKEY. If the table order is not important, then use only the fields that are used in the subsequent calls of SETRANGE and SETFILTER. If the definition of the key still includes the fields that are specified in the call of SETCURRENTKEY in the order given, then you can change the definition of the key without having to change any code.

Expand image Example 1

This example shows how to use the SETCURRENTKEY function without using a return value. This example requires that you create the following variable.

Name | DataType | Subtype
MyCustomer | Record | Customer
CopyCode image Copy Code
MyCustomer.SETCURRENTKEY(Name);

This statement selects the Name key for the Customer table. If the key cannot be found, a run-time error occurs.

Expand image Example 2

This example shows how to use the SETCURRENTKEY function with a return value.

This example requires that you create the following variable.

Name | DataType | Subtype
MyCustomer | Record | Customer

This example requires that you create the following text constants.

Name | ConstValue
Text000 | The key was successfully selected.
Text001 | The key could not be found.
CopyCode image Copy Code
IF MyCustomer.SETCURRENTKEY(Name) THEN
  MESSAGE(Text000)
ELSE
  MESSAGE(Text001);

By including a return value, you can avoid a run-time error if a key cannot be found.

Expand image See Also

Reference

Record Data Type


SETFILTER Function (Record)

SETFILTER Function (Record)
See Also Example
CollapseAll image

Assigns a filter to a field that you specify.

Record.SETFILTER(Field, String, [Value],...)

Parameters

Record

Type: Record

The record that contains the field that you want to filter.

Field

Type: Field

The field that you want to filter.

String

Type: Text or code

The filter expression. A valid expression consists of alphanumeric characters and one or more of the following operators: <, >, *, &, |, and =. You can use replacement fields (%1, %2, and so on) to insert values at run-time.

Value

Type: Any

Replacement values to insert in replacement fields in the filter expression. The data type of Value must match the data type of Field.

Expand image Remarks

If the function is called with a field for which a filter already exists, that filter will be removed before the new one is set. You can construct filters using the following operators:

  • .. Range

  • & And

  • | Or

  • < Less than

  • <= Less than or equal to

  • > Greater than

  • >= Greater than or equal to

  • <> Different from

  • * Forms a part of value

  • @ Case-insensitive

Expand image Example

The following table shows examples of filters.

Filter | Description
A..Z | A range from A to Z
A|G | A or G
F.. & *A/S | A range from F and A/S is included in the field
<>B | All except B
<>'' | All not blank
<=200 | >500 | All less than or equal to 200 or greater than 500

The following code examples show how to use the SETFILTER function.

This example requires that you create the following variable.

Name | DataType | Subtype
GLAccountRec | Record | G/L Account
CopyCode image Copy Code
// Using a filter with replacement field.
// This filter selects all accounts in the range from 100 to 200
//   and No. 300.
GLAccountRec.SETFILTER("No.", '%1..%2|%3', '100', '200', '300');
// Using a filter entered directly in a string.
// This filter, which is entered as a string, has the same result as
//   the previous example.
//   This filter selects all accounts in the range from 100 to 200 and
//   and No. 300.
GLAccountRec.SETFILTER("No.", '100..200|300');

Expand image See Also

Reference

Record Data Type


SETPERMISSIONFILTER Function (Record)

SETPERMISSIONFILTER Function (Record)
See Also Example
CollapseAll image

Applies the user's security filter to a Record variable.

Record.SETPERMISSIONFILTER

Expand image Remarks

The security filter is combined with other filters that are placed on the Record variable with the SETFILTER Function (Record) or the SETRANGE Function (Record).

The combined filter will not include any records outside the range of the security filter. This will prevent a run-time permission error from occurring when you read the records. If SETPERMISSIONFILTER is not set and if you attempt to read a record that is outside the range of the user's security filter, a permission error can occur.

This C/AL function only applies to Microsoft Dynamics NAV with Microsoft SQL Server.

Security filters are an essential part of record-level security. Security filters limit the access that a user has so that they can only access the records, in the tables that they have permissions for, that match the criteria specified in the security filter.

For more information about record level security, see Supporting Record-Level Security.

Expand image Example

This example finds the first record within your read permission security filter. This example requires that you create the following variable in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerRec.SETPERMISSIONFILTER;
CustomerRec.FIND('-');

This example determines whether you have any read permission by setting the current filter as your security filter. This example requires that you create the following variable in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerRec.SETPERMISSIONFILTER;
If CustomerRec.READPERMISSION THEN
  MESSAGE('You have some read permissions to Customer.')
ELSE
  MESSAGE('You have no read permission to Customer.');

Expand image See Also

Reference

Record Data Type


SETPOSITION Function (Record)

SETPOSITION Function (Record)
See Also
CollapseAll image

Sets the fields in a primary key on a record to the values specified in the supplied string. The remaining fields are not changed.

Record.SETPOSITION(String)

Parameters

String

Type: Text or code

Expand image See Also

Reference

Record Data Type


SETRANGE Function (Record)

SETRANGE Function (Record)
See Also Example
CollapseAll image

Sets a simple filter, such as a single range or a single value, on a field.

Record.SETRANGE(Field [,FromValue] [,ToValue])

Parameters

Record

Type: Record

The record that contains the field that you want to filter.

Field

Type: Field

The field that you want to filter.

FromValue

Type: Any

The lower limit of the range. The data type of this parameter must match the data type of Field.

ToValue

Type: Any

The upper limit of the range. If you omit this parameter, the value that you specified for FromValue is used. The data type of this parameter must match the data type of Field.

Expand image Remarks

SETRANGE is a quick way to set a simple filter on a field.

SETRANGE removes any filters that were set previously and replaces them with the FromValue and ToValue parameters that you specify.

If you use SETRANGE without setting the FromValue and ToValue parameters, the function removes any filters that are already set.

If you set only the FromValue, the ToValue is set to the same value as the FromValue.

Expand image Example

This example shows how to use the SETRANGE function to specify that you want to see only customers 100 through 200. This example requires that you create the following variable in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerRec.SETRANGE("No.", '100', '200');
// The above statement is a quick way to set the same filter as:
CustomerRec.SETFILTER("No.", '>=100&<=200');

This example shows how to find the first record that has a blank for the requested delivery date. It requires that you create the following variable.

Name | Data type | Subtype
SalesLineRec | Record | Sales Line
CopyCode image Copy Code
SalesLineRec.SETRANGE("Requested Delivery Date",0D);
IF SalesLineRec.FIND('-') THEN
  MESSAGE('Sales Order %1 has no requested delivery date.', SalesLineRec."Document No.");

Expand image See Also

Reference

Record Data Type


SETRECFILTER Function (Record)

SETRECFILTER Function (Record)
See Also Example
CollapseAll image

Sets the values in the current key of the current record as a record filter.

Record.SETRECFILTER

Expand image Example

You can use this function to set a filter on a table before running a report. Enter C/AL code similar to the following example in the OnPush Trigger of a command button or menu item on a form. When the code is triggered, the current key fields of the current record in the form will be used as a filter when the report is run.

This example requires that you create the following variable in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerRec.SETRECFILTER;
REPORT.RUN(REPORT::"111",FALSE,FALSE,CustomerRec);

Expand image See Also

Reference

Record Data Type


SETVIEW Function (Record)

SETVIEW Function (Record)
See Also
CollapseAll image

Sets the current sort order, key, and filters on a table.

Record.SETVIEW(String)

Parameters

String

Type: Text or code

The string format is the same as the SourceTableView Property on forms.

Expand image Remarks

The value of the String parameter can be returned by the GETVIEW Function (Record).

If the SETVIEW function is executed with an empty string, all filters are removed and the primary key is used.

Expand image See Also

Reference

Record Data Type


TABLECAPTION Function (Record)

TABLECAPTION Function (Record)
See Also
CollapseAll image

Returns the current caption of a table as a string.

Caption := Record.TABLECAPTION

Expand image Property Value/Return Value

Type: Text or code

The caption, as a string.

Expand image Remarks

TABLECAPTION returns the caption of a table. TABLECAPTION first looks for a CaptionML Property. If it does not find one, it uses the Name Property. This means that TABLECAPTION has multilanguage functionality.

Expand image See Also

Reference

FIELDCAPTION Function (Record)
CAPTION Function (Form)
Record Data Type

Concepts

Working with Multilanguage Functionality


TABLENAME Function (Record)

TABLENAME Function (Record)
See Also
CollapseAll image

Returns the name of a C/SIDE table.

Name := Record.TABLENAME

Parameters

Record

Type: Record

The record in the table for which you want to find the table name.

Expand image Property Value/Return Value

Type: Text or code

The name of the table.

Expand image Remarks

The TABLECAPTION Function (Record) retrieves the Caption Property of the table. If you want to enable your application for multilanguage functionality now or in the future, you must use the TABLECAPTION function instead of the TABLENAME function.

Expand image See Also

Reference

Record Data Type

Concepts

Working with Multilanguage Functionality


TESTFIELD Function (Record)

TESTFIELD Function (Record)
See Also Example
CollapseAll image

Tests whether the contents of a field match a given value.

Record.TESTFIELD(Field, [Value])

Parameters

Record

Type: Record

The record that contains the field that you want to test.

Field

Type: Field

The field that you want to test.

Value

Type: Any

The value that you want to compare to Field. The data type of this parameter must match the data type of Field. If you include this optional parameter and the contents of Field do not match, an error message is displayed. If you omit this parameter and the contents of Field is zero or blank (empty string), an error message is displayed.

Expand image Remarks

If the contents of the field differ from the given value, an error message is displayed.

Expand image Example

This example shows how to use the TESTFIELD function without the Value parameter. This example requires that you create the following variable in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerRec."No." := '';
CustomerRec.TESTFIELD("No.")

The following error message is displayed:

You must specify No. in Customer No.=''.

This example shows how to use the TESTFIELD function with the Value parameter. This example requires that you create the following variable in the C/AL Globals window.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
CopyCode image Copy Code
CustomerRec."No." := 'AAA 1050';
CustomerRec.TESTFIELD("No.",'1000')

If No. is not 1000, then the following message is displayed:

No. must be 1000 in Customer No.='AAA 1050'.

Expand image See Also

Reference

Record Data Type


TRANSFERFIELDS Function (Record)

TRANSFERFIELDS Function (Record)
See Also Example
CollapseAll image

Copies all matching fields in one record to another record.

Record.TRANSFERFIELDS(FromRecord [, InitPrimaryKeyFields])

Parameters

Record

Type: Record

The record to which you want to copy the contents of the fields in FromRecord.

FromRecord

Type: Record

The record from which to copy.

InitPrimaryKeyFields

Type: Boolean

Default: true

If this parameter is true and the records are in the same table, both the timestamp and the Primary Key fields of the destination record will be changed.

If this parameter is true and the records are not in the same table, the Primary Key fields of the destination record will be changed (if the fields fulfill the conditions specified above) but the timestamp of the destination record will not be changed.

If this parameter is false, the timestamp or the Primary Key fields of the destination record will not change.

Expand image Remarks

TRANSFERFIELDS copies fields based on the Field No. Property of the fields. For each field in Record (the destination), the contents of the field with the same Field No. in FromRecord (the source) will be copied, if such a field exists.

The fields must have the same data type for the copying to succeed (text and code are convertible, other types are not.) There must be room for the actual length of the contents of the field to be copied in the field to which it is to be copied. If any of these conditions are not fulfilled, a run-time error will occur.

Expand image Example

This example shows how to use the TRANSFERFIELDS function with a BLOB field. If you are copying a record that contains a BLOB field, you must calculate the BLOB field before it can be copied with the rest of the record. This example requires that you create the following variables in the C/AL Globals window.

Variable name | DataType | Subtype
GLAccountRec | Record | G/L Account
FromRecord | Record | G/L Account
CopyCode image Copy Code
…
IF GLAccountRec.Picture.HASVALUE THEN
  GLAccountRec.CALCFIELDS(Picture);
GLAccountRec.TRANSFERFIELDS(FromRecord);
GLAccountRec.INSERT(TRUE);

Expand image See Also

Reference

Record Data Type


VALIDATE Function (Record)

VALIDATE Function (Record)
See Also Example
CollapseAll image

Calls the triggers for the field you specify.

Record.VALIDATE(Field [, NewValue])

Parameters

Field

Type: Field

A field with associated triggers

NewValue

Type: Must be the same data type as Field, or a data type that is convertible.

The value to insert if Field.

Expand image Remarks

VALIDATE first checks any TableRelation Property and then executes the OnValidate (Fields) Trigger of the field.

If you omit NewValue, the function validates the current value.

Expand image Example

This example shows how to use the VALIDATE function.

When you enter an account number in a ledger, some table trigger code is executed to transfer the name of the account from the chart of accounts.

If you enter an account number in a batch job, the code which transfers the name of the account is not automatically executed. The following code specifies that the appropriate field-level trigger code must be executed.

This example requires that you create the following variable.

Variable | Data type | Subtype
GeneralLedgerEntry | Record | G/L Entry
CopyCode image Copy Code
GeneralLedgerEntry.VALIDATE("G/L AccountNo", '100');
// This corresponds to:
GeneralLedgerEntry."G/L AccountNo" := '100';
GeneralLedgerEntry.VALIDATE("G/L AccountNo");

The VALIDATE function is useful for centralizing processing and thereby making your application easier to maintain.

For example, if the OnValidate trigger of the Total Amount field performs a calculation that uses values from three other fields as operands, the calculation must be performed again if the contents of any of these fields changes.

You should avoid entering the calculation formula in the OnValidate triggers of each field because this can create errors if the calculation formula has to be changed later and you have to update the code in all the triggers. Instead, you should enter the calculation formula in the OnValidate trigger of only one of the fields and call this trigger code from the OnValidate triggers of the other fields.

Expand image See Also

Reference

Record Data Type


WRITEPERMISSION Function (Record)

WRITEPERMISSION Function (Record)
See Also
CollapseAll image

Determines if you can write to a table. This function can test for both full write permission and partial write permission that has been granted with a security filter. A write permission consists of Insert, Delete, and Modify permissions.

Ok := Record.WRITEPERMISSION

Parameters

Record

Type: Record

A record in the table from which you want to determine if you have write permission.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether you have permission to write to the table using any of the following record functions:

  • INSERT Function (Record)

  • DELETE Function (Record)

  • MODIFY Function (Record)

  • RENAME Function (Record)

  • DELETEALL Function (Record)

  • MODIFYALL Function (Record)

true if you can write to some or all of the table. false if you cannot write to the table.

Expand image Remarks

This function uses the filter that is currently applied to the Record to determine whether you have write permission. If no filter is applied, the function tests for full write permission. If a filter has been set, the function only tests for write permission within the range of the filter.

To determine whether the user has a partial read permission, because a security filter has been applied, use the SETPERMISSIONFILTER Function (Record) before testing the permission with WRITEPERMISSION.

If you do not have permission to write to a table and you attempt to write, a run-time error occurs. This function allows you to determine in advance if you have write permission. When the permissions are checked, the combination of permissions in the license file and the user's permissions in the Permission table is considered.

Expand image See Also

Reference

Record Data Type


RecordID Data Type

RecordID Data Type

This data type contains the table number and the primary key of a table. You can store a RecordID in the database but you cannot set filters on a RecordID.

Expand image See Also

Reference

GETRECORD Function (RecordID)
TABLENO Function (RecordID)


GETRECORD Function (RecordID)

GETRECORD Function (RecordID)
See Also
CollapseAll image

Returns a recordref that refers to the record identified by the recordID.

RecordRef := RecordID.GETRECORD

Parameters

RecordID

Type: RecordID

The recordID of the record for which you want the recordref.

Expand image Property Value/Return Value

Type: Recordref

The recordref of the record.

Expand image Remarks

No data is read from the database when you run this function and therefore, no other fields in the record are set. Furthermore, no filters are set on the record.

Expand image See Also

Reference

RecordID Data Type


TABLENO Function (RecordID)

TABLENO Function (RecordID)
See Also
CollapseAll image

Returns the table number of the table that is identified by RecordID. This function returns an error if the record is blank.

No := RecordID.TABLENO

Parameters

RecordID

Type: RecordID

The RecordID of the record whose number you want returned

Expand image Property Value/Return Value

Type: Integer

The number of the table.

Expand image Remarks

In previous versions of Microsoft Dynamics NAV, if a RecordID referred to a temporary table, then the table number value of the RecordID was the run-time generated sequence ID, which is from the base value of 2000100000. You could use the table number to determine if a RecordID referred to a temporary table. In Microsoft Dynamics NAV 2009, the table number value of a RecordID always contains the ID of the originating physical table and not the run-time generated sequence ID. If you previously used the TABLENO Function (RecordID) to test for the sequence number and determine if the RecordID was temporary, then you use the ISTEMPORARY Function (RecordRef) in Microsoft Dynamics NAV 2009 instead.

Expand image See Also

Reference

RecordID Data Type


RecordRef Data Type

RecordRef Data Type

A RecordRef object references a record in a table. Typically, you use a RecordRef object in functions that must apply to more than one table, not to a specific table. For example, you could use a RecordRef object in a function that loops through several tables or as a parameter of a function that is called for records of different tables.

The RecordRef object can refer to any table in the database. Use the OPEN Function (RecordRef) to use the table number to select the table that you want to access, or use the GETTABLE Function (RecordRef) to use another record variable to select the table that you want to access.

If one RecordRef variable is assigned to another RecordRef variable, then they both refer to the same table instance.

Expand image See Also

Reference

FieldRef Data Type


ADDLINK Function (RecordRef)

ADDLINK Function (RecordRef)
See Also
CollapseAll image

Adds a link to a record in a table.

[ID := ]ADDLINK(URL[, Description])

Parameters

URL, Description

Type: String

The link that you want to add to the record and an optional description.

Expand image Property Value/Return Value

Type: Integer

The ID of the URL that you want to add to the record. Every time you add a link to a form or a table, an entry is created in the Record Link system table. Each entry is given an ID.

Expand image Remarks

The URL can be a link to a Web site, a file stored on the local or on a remote computer, or a link to a Microsoft Dynamics NAV form.

Expand image See Also

Reference

RecordRef Data Type


ASCENDING Function (RecordRef)

ASCENDING Function (RecordRef)
See Also
CollapseAll image

Changes or checks the order in which a search through the table that referred to by RecordRef will be performed.

[IsAscending :=] RecordRef.ASCENDING([SetAscending])

Parameters

RecordRef

Type: RecordRef

SetAscending

Type: Boolean

Determines the order of the search.

If this parameter is true, it will search in ascending order. If this parameter is false, it will search in descending order. If you do not specify this parameter, it will check the search order.

Expand image Property Value/Return Value

Type: Boolean

Specifies the order in which a search will be performed.

Expand image Remarks

This function works in the same way as the ASCENDING Function (Record).

Expand image See Also

Reference

RecordRef Data Type


CAPTION Function (RecordRef)

CAPTION Function (RecordRef)
See Also
CollapseAll image

Returns the caption of the table that is currently selected. Returns an error if no table is selected.

Caption := RecordRef.CAPTION

Parameters

RecordRef

Type: RecordRef

The recordref that identifies the table in which you are interested.

Expand image Property Value/Return Value

Type: Text

The caption of the table.

Expand image Remarks

This function works in the same way as the TABLECAPTION Function (Record).

Expand image See Also

Reference

RecordRef Data Type


CLOSE Function (RecordRef)

CLOSE Function (RecordRef)
See Also
CollapseAll image

Closes the current form or table.

RecordRef.CLOSE

Parameters

RecordRef

Type: RecordRef

The recordref of a record in the table that you want to close.

Expand image Remarks

You must use this function if you have a number of recordrefs defined as variables because these will be maintained until the variable gets out of scope.

Expand image See Also

Reference

RecordRef Data Type


COUNT Function (RecordRef)

COUNT Function (RecordRef)
See Also
CollapseAll image

Counts the number of records that are within the filters that are currently applied to the table referred to by the recordref.

Number := RecordRef.COUNT

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table.

Expand image Property Value/Return Value

Type: Integer

The number of records in the table.

Expand image Remarks

This function returns the number of records that meet the conditions of any filters associated with the records. If no filters are set, the function shows the total number of records in the table.

Note Note

The COUNT function does not lock the table before retrieving the number of records in the table. This means that the function reads both uncommitted and committed data, which could cause the number of records that is returned to be inaccurate. To ensure that the count is accurate, use the LOCKTABLE Function (RecordRef) before you use the COUNT function.

This function works in the same way as the COUNT Function (Record).

Expand image See Also

Reference

RecordRef Data Type


COPYLINKS Function (RecordRef)

COPYLINKS Function (RecordRef)
See Also
CollapseAll image

Copies all the links from a particular record.

COPYLINKS(FromRecord)

Parameters

FromRecord

Type: Record or RecordRef

Specifies the record from which you want to copy links.

Expand image Remarks

Use this function to copy all the links from a specified record and paste the links to the current record.

The link can be a link to a Web site, a file stored on the local or on a remote computer, or a link to a Microsoft Dynamics NAV form.

Expand image See Also

Reference

RecordRef Data Type


COUNTAPPROX Function (RecordRef)

COUNTAPPROX Function (RecordRef)
See Also
CollapseAll image

Obtains an approximate count of the number of records in the table, for example, for updating progress bars or displaying informational messages.

Number := RecordRef.COUNTAPPROX

Parameters

RecordRef

Type: RecordRef

The recordref of a record in the table to be counted.

Expand image Property Value/Return Value

Type: Integer

The number of records in the table.

If a filter has been set on the record, this function will behave exactly the same as the COUNT Function (Record).

Expand image Remarks

The count is approximate because it uses statistical information maintained by SQL Server, which is not kept precisely in synchronization with modifications to the table and is not under transaction control. However, it is much faster to use this information than to perform an accurate record count under transaction control, especially when there are a large number of records in the table.

Expand image See Also

Reference

RecordRef Data Type


CURRENTKEY Function (RecordRef)

CURRENTKEY Function (RecordRef)
See Also Example
CollapseAll image

Returns the current key of the table referred to by the recordref. The current key is returned as a string.

CurrentKey := RecordRef.CURRENTKEY

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table for which you want to identify the current key.

Expand image Property Value/Return Value

Type: Text

The name of the current key of the record.

Expand image Example

This example shows how to use the CURRENTKEY function.

This example requires that you create the following text constants and variables in the C/AL Globals window.

Text constant | ENU value
Text000 | The current key in the "%1" table is "%2".
Variable | Data type
RecRef | RecordRef
CopyCode image Copy Code
RecRef.OPEN(18);
MESSAGE(Text000,RecRef.CAPTION,RecRef.CURRENTKEY)

RecRef.Open(18) - Opens table 18 or causes a run-time error if table 18 does not exist.

RecRef.Caption - Returns the caption of the table.

RecRef.CURRENTKEY - Returns the caption of the current key in the table.

Expand image See Also

Reference

RecordRef Data Type


CURRENTKEYINDEX Function (RecordRef)

CURRENTKEYINDEX Function (RecordRef)
See Also
CollapseAll image

Returns or sets the current key of the table referred to by the recordref. The current key is set or returned as a number. This first key = 1, and so on.

[CurrKeyIndex :=] RecordRef.CURRENTKEYINDEX([NewKeyIndex])

Parameters

RecordRef

Type: RecordRef

NewKeyIndex

Type: Integer

The number of the new key.

Expand image Property Value/Return Value

Type: Integer

The number of the current key.

Expand image See Also

Reference

RecordRef Data Type


DELETE Function (RecordRef)

DELETE Function (RecordRef)
See Also
CollapseAll image

Deletes a record in a C/SIDE table.

[Ok :=] RecordRef.DELETE([RunTrigger])

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the record that you want to delete.

RunTrigger

Type: Boolean

Specifies whether the code in the OnDelete trigger will be executed. If this parameter is true, the code will be executed. If this parameter is false (default), the code will not be executed.

This parameter is optional.

Expand image Property Value/Return Value

Type: Boolean

true if the record was deleted. false if the record was not deleted because it could not be found in the table, because the user did not have the correct permissions, or because the C/AL code terminated.

If the record does not exist and you do not include a return value, a run-time error will occur.

Expand image Remarks

The current key and any filters on the record have no effect on this operation. The record to delete is identified by the values in its primary key.

In a multi-user environment, another application can delete the record from the table after you read the record and before you try to delete it. The Database Management System automatically detects such a situation, which causes the RecordRef.DELETE function to fail with a run-time error.

To prevent this situation, you can lock the table while you are using it with the LOCKTABLE Function (RecordRef).

Expand image See Also

Reference

RecordRef Data Type
OnDelete Trigger


DELETEALL Function (RecordRef)

DELETEALL Function (RecordRef)
See Also
CollapseAll image

Deletes all records in a C/SIDE table that fall within a specified range.

RecordRef.DELETEALL([RunTrigger])

Parameters

RecordRef

Type: RecordRef

Identifies the table in which the deletion will occur. Only those records selected by the filters set for recordref are deleted.

RunTrigger

Type: Boolean

Specifies whether the code in the OnDelete trigger will be executed. If this parameter is true, the code will be executed. If this parameter is false (default), the code will not be executed.

This parameter is optional.

Expand image Remarks

This function works the same way as the DELETEALL Function (Record).

Expand image See Also

Reference

RecordRef Data Type
OnDelete Trigger


DELETELINK Function (RecordRef)

DELETELINK Function (RecordRef)
See Also
CollapseAll image

Deletes a link that has been added to a record in a table.

DELETELINK(ID)

Parameters

ID

Type: Integer

Expand image Remarks

Every time you add a link to a form or a table an entry is created in the Record Link system table. Each entry is given an ID.

Expand image See Also

Reference

RecordRef Data Type


DELETELINKS Function (RecordRef)

DELETELINKS Function (RecordRef)
See Also
CollapseAll image

Deletes all of the links that have been added to a record.

DELETELINKS

Expand image See Also

Reference

RecordRef Data Type


DUPLICATE Function (RecordRef)

DUPLICATE Function (RecordRef)
See Also
CollapseAll image

Duplicates the table that contains the RecordRef.

RecordRef := RecordRef.DUPLICATE

Parameters

RecordRef

Type: RecordRef

The RecordRef that identifies the record and the table that you want to duplicate.

Expand image Property Value/Return Value

Type: RecordRef

Expand image Remarks

The RecordRef that is returned refers to a new record with the same filters, current keys, and marks as the original RecordRef. Any changes that you make to the filters, current keys, and marks of the new record are not observed in the original. This is different from assigning one RecordRef to another RecordRef. If you assign one RecordRef to another RecordRef, then both refer to the same record and changes that you make to one RecordRef are observed in the other RecordRef.

Expand image See Also

Reference

RecordRef Data Type


FIELD Function (RecordRef)

FIELD Function (RecordRef)
See Also
CollapseAll image

Returns a FieldRef for the field that has the number fieldno in the table that is currently selected. If no field has this number, the function returns an error.

Field := RecordRef.FIELD(FieldNo)

Parameters

RecordRef

Type: RecordRef

The recordref of the record for which you want the fieldref.

FieldNo

Type: Integer

The number that the field has in the table that is currently selected. This is the field for which you want the fieldref.

Expand image Property Value/Return Value

Type: FieldRef

Expand image Remarks

This function returns an error if the record is not opened and if the field is not found.

You might obtain better performance by using the FIELDINDEX Function (RecordRef).

Expand image See Also

Reference

RecordRef Data Type


FIELDCOUNT Function (RecordRef)

FIELDCOUNT Function (RecordRef)
See Also
CollapseAll image

Returns the number of fields in the table that are currently selected or returns the number of fields that have been defined in a key. Returns an error if no table or no key is selected.

Count := RecordRef.FIELDCOUNT

Parameters

RecordRef

Type: RecordRef

The recordref of the record that you use to identify the table.

Expand image Property Value/Return Value

Type: Integer

The number of fields in the table.

Expand image See Also

Reference

RecordRef Data Type


FIELDEXIST Function (RecordRef)

FIELDEXIST Function (RecordRef)
See Also
CollapseAll image

Determines if the field that has the number fieldno exists in the table that is referred to by the recordref. Returns an error if no table is currently selected.

Exist := RecordRef.FIELDEXIST(FieldNo)

Parameters

RecordRef

Type: RecordRef

The recordref that identifies the record and the table in which you are interested.

FieldNo

Type: Integer

The fieldno that you want to know whether it exists in the table.

Expand image Property Value/Return Value

Type: Boolean

true if the field exists in the table; otherwise, false.

Expand image See Also

Reference

RecordRef Data Type


FIELDINDEX Function (RecordRef)

FIELDINDEX Function (RecordRef)
See Also
CollapseAll image

Returns the fieldref of the field that has the index in the table referred to by the recordref.

Field := RecordRef.FIELDINDEX(Index)

Parameters

RecordRef

Type: RecordRef

Index

Type: Integer

Expand image Property Value/Return Value

Type: FieldRef

The fieldref of the field that is in the index.

Expand image Remarks

The first field in the index must have index 1, the second index 2, and so on. The last field must have index = FIELDCOUNT. If the index is out of the range supplied or if no table is selected, the function returns an error.

Expand image See Also

Reference

RecordRef Data Type


FILTERGROUP Function (RecordRef)

FILTERGROUP Function (RecordRef)
See Also
CollapseAll image

Changes the filter group that is being applied to the table. You can also use this function to return the number of the current filtergroup. You cannot return the number of the filtergroup and set a new filtergroup at the same time.

[CurrGroup :=] RecordRef.FILTERGROUP([NewGroup])

Parameters

RecordRef

Type: RecordRef

The recordref that is used to identify the table.

NewGroup

Type: Integer

Expand image Property Value/Return Value

Type: Integer

Expand image Remarks

A filtergroup can contain a filter for a RecordRef that has been set earlier with SETFILTER or SETRANGE. The total filter applied is the combination of all the filters set in all the filtergroups.

This function works the same way as the FILTERGROUP Function (Record).

Expand image See Also

Reference

RecordRef Data Type


FIND Function (RecordRef)

FIND Function (RecordRef)
See Also
CollapseAll image

Finds a record in a table based on the values stored in the key fields.

[Ok :=] RecordRef.FIND([Which])

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table in which you want to find a record.

Which

Type: Text or code

Specifies how to perform the search. The table will be searched until the record is found or there are no more records. Each character in the string can be present only once. You can use the following characters:

  • = search for a record that equals the key values (default)

  • > search for a record that is larger than the key values

  • < search for a record that is less than the key values

  • + search for the last record in the table (+ can only be used alone)

  • - search for the first record in the table (- can only be used alone)

You can combine the '=', '<', and '>' characters.

If this parameter contains '=', '>', or '<', then you must assign value to all fields of the current and primary keys before you call FIND.

Expand image Property Value/Return Value

Type: Boolean

true if the record was found; otherwise, false.

If you omit this optional return value and the record cannot be found, a run-time error occurs. If you include a return value, it is assumed that you will handle any errors.

Expand image Remarks

FIND retrieves the first record that meets the conditions set by the Which parameter and the filters associated with the record. The search path reflects the sort order defined by the current key. If the current key is not the primary key, there is a chance that several records might have the same values in current key fields. If this happens, the sort order defined by the primary key is used as the search path.

Expand image See Also

Reference

RecordRef Data Type


FINDFIRST Function (RecordRef)

FINDFIRST Function (RecordRef)
See Also Example
CollapseAll image

Finds the first record in a table based on the current key and filter.

[Ok :=] RecordRef.FINDFIRST

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table in which you want to find a record.

If the record is found, it is returned in RecordRef and any FlowFields in the record are set to zero. You must update any FlowFields using CALCFIELDS Function (Record).

Expand image Property Value/Return Value

Type: Boolean

true if the record was found; otherwise, false.

If you omit this optional return value and if the record cannot be found, a run-time error occurs. If you include a return value, it is assumed that you will handle any errors.

Expand image Remarks

You should use this function instead of FIND('-') when you need only the first record.

You should use this function only when you explicitly want to find the first record in a table or set. Do not use this function in combination with REPEAT..UNTIL.

Expand image Example

This example shows how to use the FINDFIRST function.
CopyCode image Copy Code
// Read the first record only.
IF SalesSetup.FINDFIRST THEN BEGIN
  ConfigurePost(SalesSetup);
END;

Expand image See Also

Reference

RecordRef Data Type
FIND Function (RecordRef)
FINDLAST Function (RecordRef)
FINDSET Function (RecordRef)


FINDLAST Function (RecordRef)

FINDLAST Function (RecordRef)
See Also Example
CollapseAll image

Finds the last record in a table based on the current key and filter.

[Ok :=] RecordRef.FINDLAST

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table in which you want to find the last record.

If the record is found, it is returned in RecordRef and any FlowFields in the record are set to zero. You must update any FlowFields using CALCFIELDS Function (Record).

If the record is not found and if you omitted the return value, a run-time error occurs.

Expand image Property Value/Return Value

Type: Boolean

true if the record was found; otherwise, false.

If you omit this optional return value and if the record cannot be found, a run-time error occurs. If you include a return value, it is assumed that you will handle any errors.

Expand image Remarks

You should use this function instead of FIND('+') when you need only the last record.

You should use this function only when you explicitly want to find the last record in a table or set. Do not use this function in combination with REPEAT..UNTIL.

Expand image Example

This example shows how to use the FINDLAST function.
CopyCode image Copy Code
// Read the last record only.
IF GLEntry.FINDLAST THEN;

Expand image See Also

Reference

RecordRef Data Type
FIND Function (RecordRef)
FINDFIRST Function (RecordRef)
FINDSET Function (RecordRef)


FINDSET Function (RecordRef)

FINDSET Function (RecordRef)
See Also
CollapseAll image

Finds a set of records in a table based on the current key and filter. FINDSET can only retrieve records in ascending order.

[Ok :=] RecordRef.FINDSET([ForUpdate][,UpdateKey])

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table in which you want to find the set of records.

If the record is found, it is returned in RecordRef and any FlowFields in the record are set to zero. You must update any FlowFields using CALCFIELDS Function (Record).

If the record is not found and if you omitted the return value, a run-time error occurs.

ForUpdate

Type: Boolean

Set this parameter to false if you do not want to modify any records in the set. Set this parameter to true if you want to modify records in the set.

If you set this parameter to true, the LOCKTABLE Function (RecordRef) is immediately performed on the table before the records are read.

UpdateKey

Type: Boolean

This parameter only applies if ForUpdate is true.

If you are going to modify any field value within the current key, set this parameter to true.

Expand image Property Value/Return Value

Type: Boolean

true if the record set was found; otherwise, false.

If you omit this optional return value and if the record cannot be found, a run-time error occurs. If you include a return value, it is assumed that you will handle any errors.

Expand image Remarks

You should use this function only when you explicitly want to loop through a recordset. You should only use this function in combination with REPEAT..UNTIL.

Furthermore, FINDSET only allows you to loop through the recordset from the top down. If you want to loop from the bottom up, you should use FIND(‘+’).

The general rules for using FINDSET are the following:

  • FINDSET(FALSE,FALSE) - Read-only. This uses no server cursors and the record set is read with a single server call.

  • FINDSET(TRUE,FALSE) - This is used to update non-key fields. This uses a cursor with a fetch buffer similar to FIND(‘-’).

  • FINDSET(TRUE,TRUE) - This is used to update key fields.

This function is designed to optimize finding and updating sets. If you set any or both of the parameters to false, you can still modify the records in the set but these updates will not be performed optimally.

This function works the same way as the FINDSET Function (Record).

Expand image See Also

Reference

RecordRef Data Type
FIND Function (RecordRef)
FINDFIRST Function (RecordRef)
FINDLAST Function (RecordRef)


GET Function (RecordRef)

GET Function (RecordRef)
See Also
CollapseAll image

Finds a record based on the ID of the record.

[Ok :=] RecordRef.GET(RecordID)

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table.

RecordID

Type: RecordID

This field object contains the table number and the primary key of the table and is used to identify the record that you want to find.

Expand image Property Value/Return Value

Type: Boolean

true if the record was found; otherwise, false.

If you omit this optional return value and if the record cannot be found, then a run-time error occurs. If you include the return value, it is assumed that you will handle any errors.

Expand image Remarks

This function always uses the primary key for the table and ignores any filters. The current key and filters are not changed after you call this function.

Expand image See Also

Reference

RecordRef Data Type


GETFILTERS Function (RecordRef)

GETFILTERS Function (RecordRef)
See Also
CollapseAll image

Determines which filters have been applied to the table referred to by the recordref.

String := RecordRef.GETFILTERS

Parameters

RecordRef

Type: RecordRef

The recordref that is used to identify the record for which you want to find out the filters that have been applied.

Expand image Remarks

This function works the same way as the GETFILTERS Function (Record).

Expand image Property Value/Return Value

Type: Text

Expand image See Also

Reference

RecordRef Data Type


GETPOSITION Function (RecordRef)

GETPOSITION Function (RecordRef)
See Also
CollapseAll image

Returns a string that contains the primary key of the current record.

String := RecordRef.GETPOSITION([UseNames])

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the record for which you want to know the primary key.

UseNames

Type: Boolean

If this parameter is true (default) or if it is empty, the returned string contains references to field names in the table with which the record is associated. If the parameter is false, the returned string contains references to field numbers in the table with which the record is associated.

This parameter is optional.

Expand image Property Value/Return Value

Type: Text or code

The string has the same format as the SourceTableRecord Property on a form.

Expand image Remarks

This function works the same way as the GETPOSITION Function (Record).

Expand image See Also

Reference

RecordRef Data Type


GETTABLE Function (RecordRef)

GETTABLE Function (RecordRef)
See Also
CollapseAll image

Makes a recordref variable use the same table instance as a record variable.

RecordRef.GETTABLE(rec)

Parameters

RecordRef

Type: Recordref

The recordref that refers to the table in which you are interested.

rec

Type: Record

Expand image See Also

Reference

RecordRef Data Type
SETTABLE Function (RecordRef)


GETVIEW Function (RecordRef)

GETVIEW Function (RecordRef)
See Also
CollapseAll image

Returns a string that describes the current sort order, key, and filters on a table.

String := RecordRef.GETVIEW([UseNames])

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table.

If no table is selected, the function returns an empty string.

UseNames

Type: Boolean

If this parameter is true (default) or if it is empty, the returned string contains references to field captions in the table with which the record is associated. If this parameter is false, the returned string contains references to field numbers in the table with which the record is associated.

This parameter is optional.

Expand image Property Value/Return Value

Type: Text or code

The string format is the same as the SourceTableView Property on forms.

Expand image Remarks

If the SETVIEW Function (RecordRef) has been executed, the String parameter will return the value set by SETVIEW.

This function works the same way as the GETVIEW Function (Record).

Expand image See Also

Reference

RecordRef Data Type


HASFILTER Function (RecordRef)

HASFILTER Function (RecordRef)
See Also
CollapseAll image

Determines whether a filter has been applied to the table referred to by a recordref.

Ok := RecordRef.HASFILTER

Parameters

RecordRef

Type: RecordRef

The recordref that is used to identify the table.

Expand image Property Value/Return Value

Type: Boolean

true if the table referred to by RecordRef has a filter; otherwise, false.

If you omit this return value and if the record cannot be found, a run-time error occurs. If you include the return value, it is assumed that you will handle any errors.

Expand image Remarks

This function works the same way as the HASFILTER Function (Record).

Expand image See Also

Reference

RecordRef Data Type


HASLINKS Function (RecordRef)

HASLINKS Function (RecordRef)
See Also
CollapseAll image

Determines whether a record contains any links.

OK := HASLINKS

Expand image Property Value/Return Value

Type: Boolean

true if the record contains at least one link; otherwise, false.

Expand image Remarks

The link can be a link to a Web site, a file stored on the local computer or on a remote computer, or a link to a Microsoft Dynamics NAV form.

Expand image See Also

Reference

RecordRef Data Type


INIT Function (RecordRef)

INIT Function (RecordRef)
See Also
CollapseAll image

Initializes a record in a table.

RecordRef.INIT

Parameters

RecordRef

Type: RecordRef

The recordref that is used to identify the record that you want to initialize.

Expand image Remarks

This function assigns default values to each field in the record. The values that are assigned in the record correspond to those defined when the table was created. If no value was assigned when the table was created, the values are assigned based on the data type, as shown in the following table.

Data type | Default value
BigInteger | 0
BigText | <Empty>
Binary | <Empty>
BLOB | <Empty>
Boolean | No
Code | '' (empty string)
Date | 0d (Undefined date)
DateFormula | '' (empty string)
DateTime | 0DT (Undefined datetime)
Decimal | 0.0
Duration | 0
GUID | 00000000-0000-0000-0000-000000000000
Integer | 0
Option | 0
RecordID | <Empty>
TableFilter | <Empty>
Text | '' (empty string)
Time | 0T (Undefined time)

Primary key and timestamp fields are not initialized.

After the function executes, you can change the values in any or all of the fields before you call the INSERT Function (RecordRef) to enter the record in the table. Be sure that the fields that make up the primary key contain values that make the total primary key unique. If the primary key is not unique (such as the record already exists), then the record is rejected.

The function works the same as the INIT Function (Record).

Expand image See Also

Reference

RecordRef Data Type


INSERT Function (RecordRef)

INSERT Function (RecordRef)
See Also
CollapseAll image

Inserts a record into a table.

[Ok :=] RecordRef.INSERT([RunTrigger])

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the record that you want to insert.

RunTrigger

Type: Boolean

Specifies whether to run the C/AL code in the OnInsert Trigger.

If this parameter is true, the code on the OnInsert trigger will be executed.

If this parameter is false, the code on the OnInsert trigger will not be exectued.

Expand image Property Value/Return Value

Type: Boolean

true if the record was inserted; otherwise, false.

If you omit this optional return value and if the record cannot be inserted, a run-time error occurs. If you include the return value, you must handle any errors.

Expand image Remarks

Records are uniquely identified by the values in primary key fields. The C/SIDE Database Management System (DBMS) checks the primary key for the table before it inserts a new record.

If the table contains an auto-increment field, the auto-increment feature is used if the record contains a zero value in that field. The auto-increment feature enters the new value into the field as part of the insert.

If the auto-increment field contains a non-zero value, that value is inserted into the table and the auto-increment feature is not used. If the value in the auto-increment field is greater than the last auto-increment value in the table, the next auto-increment value that is entered into the table will be greater than the value in the field that you just inserted. If the value in the auto-increment field already exists in the table, a run-time error occurs.

This function works the same as the INSERT Function (Record).

Expand image See Also

Reference

RecordRef Data Type


ISEMPTY Function (RecordRef)

ISEMPTY Function (RecordRef)
See Also
CollapseAll image

Determines whether any records exist within a filtered set of records in a table.

Empty := RecordRef.ISEMPTY

Parameters

RecordRef

Type: RecordRef

The recordref of a record that refers to a table (possibly with filters).

Expand image Property Value/Return Value

Type: Boolean

Expand image Remarks

If you have not applied filters to the record, this function determines whether the table is empty. If you have applied filters, the function determines whether the filtered set of records is empty.

The number of filters that you have applied to the records affects the speed of the ISEMPTY function. The fewer the number of filters, the faster the operation is performed.

When you are using SQL Server, this function is faster than using the COUNT Function (Record) and then testing the result for zero.

This function works the same as the ISEMPTY Function (Record).

Expand image See Also

Reference

RecordRef Data Type


ISTEMPORARY Function (RecordRef)

ISTEMPORARY Function (RecordRef)
See Also Example
CollapseAll image

Determines whether a RecordRef refers to a temporary table.

Temp := RecordRef.ISTEMPORARY

Parameters

RecordRef

Type: RecordRef

The RecordRef of a record that refers to a table.

Expand image Property Value/Return Value

Type: Boolean

true if the RecordRef refers to a temporary table; otherwise, false.

Expand image Remarks

In previous versions of Microsoft Dynamics NAV, if a RecordID or a RecordRef referred to a temporary table, then the table number value of the RecordID or RecordRef was the run-time generated sequence ID, which is from the base value of 2000100000. You could use the table number to determine if a RecordID or a RecordRef referred to a temporary table. In Microsoft Dynamics NAV 2009, the table number value of a RecordID or a RecordRef always contains the ID of the originating physical table and not the run-time generated sequence ID. If you previously used the TABLENO Function (RecordID) or the NUMBER Function (RecordRef) to test for the sequence number and determine if the RecordID or RecordRef was temporary, then you must use the ISTEMPORARY function in Microsoft Dynamics NAV 2009 instead.

Expand image Example

This example shows that you can replace code that you used previously to determine if a RecordRef referred to a temporary table. This example requires that you create a RecordRef variable named RecordRefVar.
CopyCode image Copy Code
// Previous code
IF RecordRefVar.Number >= 2000100000 THEN BEGIN
  // Code for temporary tables
END;

// New code
IF RecordRefVar.IsTemporary THEN BEGIN
  // Code for temporary tables
END;

Expand image See Also

Reference

RecordRef Data Type


KEYCOUNT Function (RecordRef)

KEYCOUNT Function (RecordRef)
See Also
CollapseAll image

Returns the number of keys that exist in the table that is referred to by the recordref. Returns an error if no table is selected.

Count := RecordRef.KEYCOUNT

Parameters

RecordRef

Type: RecordRef

The recordref that identifies the record and the table in which you are interested.

Expand image Property Value/Return Value

Type: Integer

The amount of keys that have been identified in the table.

Expand image See Also

Reference

RecordRef Data Type


KEYINDEX Function (RecordRef)

KEYINDEX Function (RecordRef)
See Also
CollapseAll image

Returns the keyref of the key that has the index specified in the table that is currently selected.

Key := RecordRef.KEYINDEX(Index)

Parameters

RecordRef

Type: RecordRef

The recordref that identifies the record and the table in which you are interested.

Index

Type: Integer

The number of the index in which you are interested.

Expand image Property Value/Return Value

Type: KeyRef

The keyref of the field that has the index specified.

Expand image Remarks

The first key in the index must have index 1, the second index 2, and so on. The last key must have index = KEYCOUNT. If the index is out of the range supplied or if no table is selected, the function returns an error.

Expand image See Also

Reference

RecordRef Data Type


LOCKTABLE Function (RecordRef)

LOCKTABLE Function (RecordRef)
See Also
CollapseAll image

Locks a table to protect it from write transactions that conflict with each other.

RecordRef.LOCKTABLE([Wait] [, VersionCheck])

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table that you want to lock.

Wait

Type: Boolean

Specifies what to do if the table is already locked.

If this parameter is true and if another application has already locked the table, the system will wait until the table is unlocked.

If this parameter is false and if another application has already locked the table, a run-time error occurs.

VersionCheck

Type: Boolean

If this parameter is true, the version will be checked. If this parameter is false, blank, or not used, the version will not be checked.

Expand image Remarks

Because all write operations automatically lock the table in use, LOCKTABLE would appear unnecessary. However, you could have a transaction in which an application wants to inspect data and then only possibly change it, with a guarantee that the data being changed has not been modified by other applications since the read operation. The solution is to explicitly lock the table before the read operation. This ensures that no other application makes changes between the read operation and the possible write operation.

This function works the same as the LOCKTABLE Function (Record).

Expand image See Also

Reference

RecordRef Data Type


MODIFY Function (RecordRef)

MODIFY Function (RecordRef)
See Also
CollapseAll image

Modifies a record in a C/SIDE table.

[Ok :=] RecordRef.MODIFY([RunTrigger])

Parameters

RecordRef

Type: RecordRef

The recordref that identifies the record that you want to change.

RunTrigger

Type: Boolean

Specifies whether to run the C/AL code in the OnModify Trigger trigger.

If this parameter is true then the code will be executed. If this parameter is false (default) then the code will not be executed.

Expand image Property Value/Return Value

Type: Boolean

true if the record was modified; otherwise, false.

If you omit this optional return value and if the record cannot be found, a run-time error occurs. If you include the return value, you must handle any errors.

Expand image Remarks

Select the record that you want to replace by using the primary key fields. The record's current key and filters do not affect the operation.

In multi-user environments, another application could modify the record between the time you read the record and when you attempt to modify it. The C/SIDE Database Management System (DBMS) automatically watches for this and, if a conflict occurs, cancels the MODIFY function and displays an error message.

This function works the same as the MODIFY Function (Record).

Expand image See Also

Reference

MODIFYALL Function (Record)
RecordRef Data Type


NAME Function (RecordRef)

NAME Function (RecordRef)
See Also
CollapseAll image

Returns the name of the table that is currently selected. Returns an error if no table is selected.

Name := RecordRef.NAME

Parameters

RecordRef

Type: RecordRef

The recordref that identifies the table in which you are interested.

Expand image Property Value/Return Value

Type: Text (30)

The name of the table.

Expand image Remarks

This function works the same as the TABLENAME Function (Record).

Expand image See Also

Reference

RecordRef Data Type


NEXT Function (RecordRef)

NEXT Function (RecordRef)
See Also
CollapseAll image

Steps through a specified number of records and retrieves a record.

[Steps :=] RecordRef.NEXT([Steps])

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the record that you want to use as the starting point for the steps. The function returns 0 if no table is selected.

Steps

Type: Integer

Defines the direction of the search and how many records to step over.

If this parameter is greater than zero, the function will search Steps number of records forward in the table. If this parameter is less than zero, the function will search Steps number of records backward in the table. If this parameter is 0, it has no effect.

If you do not specify this parameter, the function finds the next record.

Expand image Property Value/Return Value

Type: Integer

Returns the number of records inspected which meet the criteria of any filters and the current key. This value can be less than Steps, depending on the number of records in the table. If the table is empty, zero is returned and the record is not changed.

Expand image Remarks

This function locates a record positioned a given number of steps forward or backward from the record specified by RecordRef. Movement through the table is governed by the filters and the current key associated with the records. The fields in the record which will be compared with the current key fields must contain appropriate values before the function is called.

This function works the same as the NEXT Function (Record).

Expand image See Also

Reference

RecordRef Data Type


NUMBER Function (RecordRef)

NUMBER Function (RecordRef)
See Also
CollapseAll image

Returns the table ID (number) of the table that contains the record that was referred to by the RecordRef.

No := RecordRef.NUMBER

Parameters

RecordRef

Type: RecordRef

The RecordRef that refers to the table in which you are interested.

Expand image Property Value/Return Value

Type: Integer

The number of the table or the number of the field.

Expand image Remarks

In previous versions of Microsoft Dynamics NAV, if a RecordRef referred to a temporary table, then the table number value of the RecordRef was the run-time generated sequence ID, which is from the base value of 2000100000. You could use the table number to determine if a RecordRef referred to a temporary table. In Microsoft Dynamics NAV 2009, the table number value of a RecordRef always contains the ID of the originating physical table and not the run-time generated sequence ID. If you previously used the NUMBER Function (RECORDREF) to test for the sequence number and determine if the RecordRef was temporary, then you must use the ISTEMPORARY Function (RecordRef) in Microsoft Dynamics NAV 2009 instead.

Expand image See Also

Reference

RecordRef Data Type


OPEN Function (RecordRef)

OPEN Function (RecordRef)
See Also Example
CollapseAll image

Causes a RecordRef variable to refer to a table which is identified by its number in a particular company.

RecordRef.OPEN(No[, Temp][, CompanyName])

Parameters

RecordRef

Type: RecordRef

No

Type: Integer

The number of the table.

Temp

Type: Boolean

CompanyName

Type: Text or code

The name of the company to which you want to change. If you omit this parameter, the current company is used.

Expand image Remarks

When you use the RecordRef.OPEN function a new object is created. This object contains references to the open table, filters, and the record itself and all the fields it contains.

If you use the CompanyName parameter, then this function works the same as the CHANGECOMPANY Function (Record).

Expand image Example

This example shows how to use the OPEN function.
CopyCode image Copy Code
recordref.OPEN(DATABASE::Customer);
message('The %1 table contains %2 records;
recordref.CAPTION, recordref.COUNTAPPROX);

This example shows how to use the OPEN function. In this example, "MyRecordRef" opens table 27 and then "FIND('-')" finds the first record in the table. "TempMyRecordRef" opens a temporary table which is empty and therefore the "FIND('-')" returns false.
CopyCode image Copy Code
MyRecordRef.OPEN(27,FALSE);
TempMyRecordRef.OPEN(27,TRUE);

IF MyRecordRef.FIND('-') THEN // This is true and will find the first record in the table.
  MESSAGE('MyRecordRef finds')
ELSE
  MESSAGE('MyRecordRef does not find');

IF TempMyRecordRef.FIND('-') THEN // This is false because there are no records in a temporary table.
  MESSAGE('TempMyRecordRef finds')
ELSE
  MESSAGE('TempMyRecordRef does not find');

Expand image See Also

Reference

GETTABLE Function (RecordRef)
CHANGECOMPANY Function (Record)
RecordRef Data Type


READCONSISTENCY Function (RecordRef)

READCONSISTENCY Function (RecordRef)
See Also
CollapseAll image

Determines whether the table supports read consistency.

Ok := RecordRef.READCONSISTENCY

Parameters

RecordRef

Type: RecordRef

Refers to a record in the table to be checked for read consistency.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether read consistency is supported.

true if the table supports read consistency; otherwise, false.

Expand image Remarks

The advantage of read consistency is that a snapshot of the data can be used in situations where you do not want the data to change during the transaction. For example, you can print a report and be sure that other users have not updated the report data. Further, this function does not negatively affect the concurrency of the system in a multi-user environment.

The Classic Database Server supports read consistency as an integral part of the database architecture. SQL Server does not support this feature. It implements a consistent snapshot by locking data as it is read to prevent other users from changing it. This significantly reduces concurrency for tables that are frequently accessed by multiple users.

This function works the same as the READCONSISTENCY Function (Record).

Expand image See Also

Reference

RecordRef Data Type


READPERMISSION Function (RecordRef)

READPERMISSION Function (RecordRef)
See Also
CollapseAll image

Determines if you can read from a table.

Ok := RecordRef.READPERMISSION

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the record in the table for which you want to know if you have read permission.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether you have permission to read from the table.

true if you can read from some or all of the table; otherwise, false.

Expand image Remarks

This function can test for both full read permission and a partial read permission that has been granted with a security filter.

This function uses the filter that is currently applied to the RecordRef to determine whether you have read permission. If no filter is applied, the function tests for full read permission. If a filter has been set, the function only tests for read permission within the range of the filter.

To determine whether the user has a partial read permission because a security filter has been applied, use the SETPERMISSIONFILTER Function (RecordRef) before testing the permission with the READPERMISSION Function (RecordRef).

If you do not have permission to read from a table and you attempt to read, a run-time error occurs. This function lets you find out in advance if you have read permission. When the permissions are checked, the combination of the permissions in the license file and the user's permissions in the Permission table is considered.

This function works the same as the READPERMISSION Function (Record).

Expand image See Also

Reference

RecordRef Data Type


RECORDID Function (RecordRef)

RECORDID Function (RecordRef)
See Also
CollapseAll image

Returns the RecordID of the record that is currently selected in the table. If no table is selected, an error is generated.

RecordID := RecordRef.RECORDID

Parameters

RecordRef

Type: RecordRef

The recordref of the record whose recordID you want to get.

Expand image Property Value/Return Value

Type: RecordID

Expand image See Also

Reference

RecordRef Data Type


RECORDLEVELLOCKING Function (RecordRef)

RECORDLEVELLOCKING Function (RecordRef)
See Also
CollapseAll image

Determines whether the table supports record-level locking.

Ok := RecordRef.RECORDLEVELLOCKING

Parameters

RecordRef

Type: RecordRef

Refers to a record in the table to be checked for this feature.

Expand image Property Value/Return Value

Type: Boolean

true if the table supports record level locking; otherwise, false.

Expand image Remarks

If you are using SQL Server, you can use record-level locking.

If you are running on the Microsoft Dynamics NAV Database Server, you cannot use record-level locking.

Expand image See Also

Reference

RecordRef Data Type


RESET Function (RecordRef)

RESET Function (RecordRef)
See Also
CollapseAll image

Removes all filters, including any special filters set by the MARKEDONLY Function (Record) and changes the current key to the primary key. Also removes any marks on the record and clears any C/AL variables on the record.

RecordRef.RESET

Parameters

RecordRef

Type: RecordRef

Refers to the record that you want to reset.

Expand image Remarks

If no table is selected, this function returns an error.

This function works the same as the RESET Function (Record).

Expand image See Also

Reference

RecordRef Data Type


SETPERMISSIONFILTER Function (RecordRef)

SETPERMISSIONFILTER Function (RecordRef)
See Also
CollapseAll image

Applies the user's security filter to a RecordRef variable. The security filter is combined with other filters that are placed on the RecordRef variable with the SETFILTER Function (Record) or SETRANGE Function (Record).

RecordRef.SETPERMISSIONFILTER

Expand image Remarks

The combined filter will not include any records outside the range of the security filter. This will prevent a run-time permission error from occurring when you read the records. If SETPERMISSIONFILTER is not set, a permission error can occur if you attempt to read a record that is outside the range of the user's security filter.

This C/AL function only applies to Microsoft Dynamics NAV with Microsoft SQL Server.

Security filters are an essential part of record level security. Security filters limit the access that a user has so that they can only access the records, in the tables that they have permissions for, that match the criteria specified in the security filter.

For more information about record level security, see Supporting Record-Level Security.

This function works the same as the SETPERMISSIONFILTER Function (Record).

Expand image See Also

Reference

RecordRef Data Type


SETPOSITION Function (RecordRef)

SETPOSITION Function (RecordRef)
See Also
CollapseAll image

Sets the fields in a primary key on a record to the values specified in the String parameter. The remaining fields are not changed.

RecordRef.SETPOSITION(String)

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the record.

Expand image Property Value/Return Value

Type: Text or code

Expand image Remarks

This function works the same as the SETPOSITION Function (Record).

Expand image See Also

Reference

RecordRef Data Type


SETRECFILTER Function (RecordRef)

SETRECFILTER Function (RecordRef)
See Also
CollapseAll image

Sets a filter on a record that is referred to by a recordref.

RecordRef.SETRECFILTER

Parameters

RecordRef

Type: RecordRef

The recordref used to identify the record on which you want to place a filter.

Expand image Remarks

This function works the same as the SETRECFILTER Function (Record).

Expand image See Also

Reference

RecordRef Data Type


SETTABLE Function (RecordRef)

SETTABLE Function (RecordRef)
See Also
CollapseAll image

Causes a record variable to use the same table instance as a recordref variable.

RecordRef.SETTABLE(rec)

Parameters

RecordRef

Type: RecordRef

Rec

Type: Record

Expand image Remarks

Any filters that are applied to the record are also applied to the recordref. If you change the filter that is applied to the recordref, you must call SETTABLE again to apply the new filter to the record.

Expand image See Also

Reference

GETTABLE Function (RecordRef)
RecordRef Data Type


SETVIEW Function (RecordRef)

SETVIEW Function (RecordRef)
See Also
CollapseAll image

Sets the current sort order, key, and filters on a table.

RecordRef.SETVIEW(String)

Parameters

RecordRef

Type: RecordRef

The recordref that refers to the table on which you want to set the current sort order, key, and filters

String

Type: Text or code

The string format is the same as the SourceTableView Property on forms.

Expand image Remarks

The value of the String parameter can be returned by the GETVIEW Function (RecordRef).

If the SETVIEW function is executed with an empty string, all the filters are removed and the primary key is used.

If no table is selected, the SETVIEW function fails.

This function works the same as the SETVIEW Function (Record).

Expand image See Also

Reference

RecordRef Data Type


WRITEPERMISSION Function (RecordRef)

WRITEPERMISSION Function (RecordRef)
See Also
CollapseAll image

Determines if you can write to a table.

Ok := RecordRef.WRITEPERMISSION

Parameters

RecordRef

Type: RecordRef

The recordref that refers to a record in the table for which you want to know if you have write permission.

Expand image Property Value/Return Value

Type: Boolean

Specifies if you have permission to write to the table using any of the following RecordRef functions:

  • INSERT Function (RecordRef)

  • DELETE Function (RecordRef)

  • MODIFY Function (RecordRef)

  • DELETEALL Function (RecordRef)

true if you can write to some or all of the table; otherwise, false.

Expand image Remarks

This function can test for both full write permission and a partial write permission that has been granted with a security filter. A write permission consists of Insert, Delete, and Modify permissions.

This function uses the filter that is currently applied to the RecordRef to determine whether you have write permission. If no filter is applied, the function tests for full write permission. If a filter has been set, the function only tests for write permission within the range of the filter.

To determine whether the user has partial write permission, because a security filter has been applied, use the SETPERMISSIONFILTER Function (RecordRef) before testing the permission with the WRITEPERMISSION function (RecordRef).

If you do not have permission to write to a table and you attempt to write, a run-time error occurs. This function lets you find out in advance if you have write permission. When the permissions are checked, the combination of permissions in the license file and the user's permissions in the Permission table is considered.

This function works the same as the WRITEPERMISSION Function (Record).

Expand image See Also

Reference

RecordRef Data Type


Report Data Type

Report Data Type

This complex data type stores reports.

Expand image Remarks

Reports contain a number of simpler elements called controls. Controls are used to display information to the user or receive information from the user.

Expand image See Also

Reference

BREAK Function (Dataport, Report, XMLport)
CREATETOTALS Function (Report)
NEWPAGE Function (Report)
NEWPAGEPERRECORD Function (Report)
OBJECTID Function (Report)
PAGENO Function (Report)
PAPERSOURCE Function (Report)
PREVIEW Function (Report)
PRINTONLYIFDETAIL Function (Report)
QUIT Function (Dataport, Report, XMLport)
REPORT.RUN Function
REPORT.RUNMODAL Function
RUN Function (Report)
RUNMODAL Function (Report)
SAVEASHTML Function (Report)
SAVEASXML Function (Report)
SETTABLEVIEW Function (Dataport, Form, Report, XMLport)
SHOWOUTPUT Function (Report)
SKIP Function (Dataport, Report, XMLport)
TOTALSCAUSEDBY Function (Report)
URL Function (Report)
USEREQUESTFORM Function (Report)


CREATETOTALS Function (Report)

CREATETOTALS Function (Report)
See Also Example
CollapseAll image

Maintains totals for a variable in the same way as totals are maintained for fields by using the TotalFields Property.

CREATETOTALS(Var1 [, Var2] ,...)

Parameters

Var1, Var2, …

Type: Decimal

Expand image Remarks

Similar to the TotalFields Property, CREATETOTALS maintains group and grand totals. The totals can be printed by placing controls that have the variable or variables that are the arguments of CREATETOTALS as their source expressions in the appropriate sections. The group totals are printed in GroupFooter sections, and the grand totals are printed in Footer sections.

This function is not supported on client report definition (RDLC) report layouts. In most cases, when you create a layout suggestion for a Classic report layout that uses the CREATETOTALS function, a SUM expression is created instead and no action is required.

Expand image Example

This example shows how to use the CREATETOTALS function to maintain totals for the two variables Amount and Quantity.
CopyCode image Copy Code
CurrReport.CREATEOTALS(Amount, Quantity);

Expand image See Also

Reference

Report Data Type


NEWPAGE Function (Report)

NEWPAGE Function (Report)
See Also Example
CollapseAll image

Forces a page break when printing a report.

NEWPAGE

Expand image Remarks

The page break generated by NEWPAGE is treated exactly like the page breaks that are generated automatically with one exception, footers and headers will be printed in the same way as when an automatic page break occurs, but transport footers and headers are not generated and printed.

This function is not supported on client report definition (RDLC) report layouts. For more information about how to group sets of data on RDLC report layouts and reset the page number after each group, see How to: Reset Page Numbers.

Expand image Example

This example shows how to use the NEWPAGE function in the OnPreSection Trigger of the Body section of the relevant data item if you have a certain table where you want to start a new page before certain records when printing a list of the table.
CopyCode image Copy Code
IF "Spare Parts".Pagebreak THEN
CurrReport.NEWPAGE;

The Pagebreak variable is supposed to be of type Boolean, and when it is true, a page break will be generated.

Expand image See Also

Reference

Report Data Type


NEWPAGEPERRECORD Function (Report)

NEWPAGEPERRECORD Function (Report)
See Also
CollapseAll image

Returns the current setting of the NewPagePerRecord Property, and sets this property to a new value.

[IsNewPagePerRecord :=] NEWPAGEPERRECORD([SetNewPagePerRecord])

Parameters

SetNewPagePerRecord

Type: Boolean

The new setting of the NewPagePerRecord property.

Expand image Property Value/Return Value

Type: Boolean

The current setting of the NewPagePerRecord property.

Expand image Remarks

This function is not supported on client report definition (RDLC) report layouts. For more information about creating new pages per record for RDLC report layouts, see How to: Create New Pages per Record.

Expand image See Also

Reference

NewPagePerRecord Property
Report Data Type


OBJECTID Function (Report)

OBJECTID Function (Report)
See Also
CollapseAll image

Returns the name or number of a report.

String := Report.OBJECTID([UseNames])

Parameters

Report

Type: Report

UseNames

Type: Boolean

This parameter is optional.

If the parameter is set to true (default value) or if it is empty, the returned string contains the name of the report.

If the parameter is set to false, the returned string (report xxx) contains the number of the report.

Expand image Property Value/Return Value

Type: Text or code

The name or the number of the report.

Expand image Remarks

This function is not supported on client report definition (RDLC) report layouts.

Expand image See Also

Reference

Report Data Type


PAGENO Function (Report)

PAGENO Function (Report)
See Also
CollapseAll image

Returns the current page number of a report and sets a new page number.

[CurrPageNo :=] PAGENO([NewPageNo])

Expand image Remarks

This function should be used in the OnPostSection Trigger of the section where you want to retrieve the current page number or set a new page number, as the system will have updated the page number.

This function is not supported on client report definition (RDLC) report layouts. For more information about how to group sets of data together on RDLC report layouts and reset the page number after each group, see How to: Reset Page Numbers.

Expand image See Also

Reference

Report Data Type


PAPERSOURCE Function (Report)

PAPERSOURCE Function (Report)
See Also
CollapseAll image

Returns the paper source used for the current page or a specified page, and sets a new paper source.

CurrReport.PAPERSOURCE(PaperBinNo [, PhysicalPage])

Parameters

PaperBinNo

The tray number. This parameter is required.

PhysicalPage

The page number. This parameter is optional.

Expand image Remarks

The PAPERSOURCE function has two parameters: the tray number, which is required, and the page number, which is optional. If the printer does not support the tray number, the function call will be ignored, and the printer will continue using the previously selected tray.

The following tray numbers correspond to the options for the PaperSourceFirstPage Property and PaperSourceOtherPages Property:

1Upper or Only One Feed

2Lower Feed

3Middle Feed

4Manual Feed

5Envelope Feed

6Envelope Manual Feed

7Automatic Feed

8Tractor Feed

9Small-format Feed

10Large-format Feed

11Large-capacity Feed

14Cassette Feed

15Automatically Select

256Printer Specific Feed 1

257Printer Specific Feed 2

258Printer Specific Feed 3

259Printer Specific Feed 4

260Printer Specific Feed 5

261Printer Specific Feed 6

262Printer Specific Feed 7

263Printer Specific Feed 8

If the printer supports other tray numbers, you can enter these too.

If you do not specify a page number, the tray change will apply to the current page. The new tray will also apply to subsequent pages until the next tray change occurs.

When you specify a page number, the tray change will take place when the specified page is printed. Subsequent pages will also use this tray until the next tray change. The tray change can be placed anywhere on a page and still apply to the whole page.

If you specify more than one paper tray selection for a page, the printer uses the last selection.

This function is not supported on client report definition (RDLC) report layouts.

Expand image See Also

Reference

Report Data Type


PREVIEW Function (Report)

PREVIEW Function (Report)
See Also Example
CollapseAll image

Indicates whether a report is being printed in preview mode.

IsPreview := PREVIEW

Expand image Property Value/Return Value

Type: Boolean

true if the report is run in preview mode; otherwise, false.

Expand image Remarks

You must use the return value. A compile error is generated if this value is not used.

Differences Between the Classic Client and RoleTailored Client

In the Classic client, if you run a report in preview mode and then call CurrReport.PREVIEW, then printing is disabled. If you click the Print icon at the bottom of the Print Preview window, then you get the following error message.

This report cannot be printed from Print Preview. Quit Print Preview and run the report.

The following illustration shows the Print icon in the Classic client Print Preview window.

Print icon in Classic request form

In the RoleTailored client, if you run a client report definition (RDLC) report layout in preview mode and then call CurrReport.PREVIEW, then the Print icon, Print Layout icon, Page Setup icon, and Save As icon are not displayed.

If you run a client report definition (RDLC) report layout in preview mode and do not call CurrReport.PREVIEW, then you can print from the Print Preview window.

The following illustration shows the Print icon in the RoleTailored client Print Preview window.

RDLC report print icon

Expand image Example

This example shows how to use the PREVIEW function. You can use this function in an application that stores a count of how many times a document has been printed in the database. This number must be updated from inside the report that is used to print the document. To avoid updating the number when the report is run in preview mode, add a construct to the OnPreDataItem trigger that is like the one that is shown in this example when adding the code that updates the count.
CopyCode image Copy Code
IF CurrReport.PREVIEW THEN
... // Preview-specific processing
ELSE
... // Processing that is not preview specific:
... //  Update the print count

Expand image See Also

Reference

Report Data Type


PRINTONLYIFDETAIL Function (Report)

PRINTONLYIFDETAIL Function (Report)
See Also
CollapseAll image

Returns the current setting of the PrintOnlyIfDetail Property and sets this property to a new value.

[IsPrintOnlyIfDetail :=] PRINTONLYIFDETAIL([SetPrintOnlyIfDetail])

Parameters

SetPrintOnlyIfDetail

Type: Boolean

The new setting of PrintOnlyIfDetail.

Expand image Property Value/Return Value

Type: Boolean

The current setting of the PrintOnlyIfDetail property.

Expand image See Also

Reference

PrintOnlyIfDetail Property
Report Data Type


REPORT.RUN Function

REPORT.RUN Function
See Also Example
CollapseAll image

Loads and executes the report that you specify.

REPORT.RUN(Number [, ReqWindow] [, SystemPrinter] [, Record])

Parameters

Number

Type: Integer

The ID of the report that you want to run. You can use the Symbols option on the View menu to select the report from a list.

If the report that you specify does not exist, a run-time error occurs.

ReqWindow

Type: Boolean

Specifies whether the request window for the report will be displayed. The request window is part of the report object.

Specify true (default) to display the request window before running the report. Specify false to run the report without showing the request window.

SystemPrinter

Type: Boolean

Specifies whether to use the default Windows printer or use the Printer Selection table to find the right printer for this report. For example, if the report prints on continuous forms, you can set up an entry in the Printer Selection table to specify to always print this report on a specific printer.

Specify true to use the printer defined as the system printer. Specify false (default) to use the printer defined through the Printer Selection table.

Record

Type: Record

Specifies which record to use in the report. Any filters attached to the record that you specify will be used.

Expand image Remarks

If at design time you do not know the specific report that you want to run, use this function or the REPORT.RUNMODAL Function. If you do know the specific report you want to run, you can use the RUN Function (Report) or the RUNMODAL Function (Report).

Expand image Example

This example shows how to run a report. This example displays the request window and sends the report to the printer selected through the Printer Selection table.
CopyCode image Copy Code
REPORT.RUN(1001);

This example shows how to run a report. This example skips the request window, starts the report immediately, and sends the report to the printer selected in the Printer Selection table.
CopyCode image Copy Code
REPORT.RUN(1001, FALSE);

This example shows how to run a report. This example skips the request window and starts the report immediately. It sends the report to the system printer instead of the printer selected through the Printer Selection table.
CopyCode image Copy Code
REPORT.RUN(1001, FALSE, TRUE);

Expand image See Also

Reference

Report Data Type


REPORT.RUNMODAL Function

REPORT.RUNMODAL Function
See Also Example
CollapseAll image

Loads and executes the report that you specify. The report is run modally.

REPORT.RUNMODAL(Number [, ReqWindow] [, SystemPrinter] [, Record])

Parameters

Number

Type: Integer

The ID of the report that you want to run. You can use the Symbols option on the View menu to select the report from a list.

If the report that you specify does not exist, a run-time error occurs.

ReqWindow

Type: Boolean

Specifies whether the request window for the report will be displayed. The request window is part of the report object.

Specify true (default) to display the request window before running the report. Specify false to run the report without showing the request window.

SystemPrinter

Type: Boolean

Specifies whether to use the default Windows printer or use the Printer Selection table to find the right printer for this report. For example, if the report prints on continuous forms, you can set up an entry in the Printer Selection table to specify to always print this report on a specific printer.

Specify true to use the printer defined as the system printer. Specify false (default) to use the printer defined through the Printer Selection table.

Record

Type: Record

Specifies which record to use in the report. Any filters attached to the record that you specify will be used.

Expand image Remarks

If at design time you do not know the specific report you want to run, use this function or the REPORT.RUN Function. If you do know the specific report you want to run, you can use the RUN Function (Report) or the RUNMODAL Function (Report).

Expand image Example

This example shows how to run a report. This example displays the request window and sends the report to the printer selected through the Printer Selection table.
CopyCode image Copy Code
REPORT.RUNMODAL(1001);

This example shows how to run a report. This example skips the request window, starts the report immediately, and sends the report to the printer selected in the Printer Selection table.
CopyCode image Copy Code
REPORT.RUNMODAL(1001, FALSE);

This example shows how to run a report. This example skips the request window and starts the report immediately. It sends the report to the system printer instead of the printer selected through the Printer Selection table.
CopyCode image Copy Code
REPORT.RUNMODAL(1001, FALSE, TRUE);

Expand image See Also

Reference

Report Data Type


RUN Function (Report)

RUN Function (Report)
See Also Example
CollapseAll image

Loads and executes the report that you specify.

Report.RUN

Parameters

Report

Type: Report

After you define this variable, you can run this function or the Report.RUNMODAL function on the variable. The variable is automatically cleared after it executes this function.

Expand image Remarks

Use this function or the RUNMODAL Function (Report) if you know at design time the exact report that you want to run. Otherwise, use the REPORT.RUNMODAL Function or REPORT.RUN Function.

If the report you specify does not exist, a compile error occurs.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
SomeReport | Report | Salesperson - Sales Statistics
CopyCode image Copy Code
CustomerRec.SETCURRENTKEY("No.");
CustomerRec.SETFILTER("Salesperson Code", 'JR|PS');
SomeReport.SETTABLEVIEW(CustomerRec);
SomeReport.RUN

Expand image See Also

Reference

Report Data Type


RUNMODAL Function (Report)

RUNMODAL Function (Report)
See Also Example
CollapseAll image

Loads and executes the report that you specify.

Report.RUNMODAL

Parameters

Report

Type: Report

After you define this variable, you can run this function or the Report.RUN function on the variable. As opposed to the Report.RUN function, the system does not automatically clear the variable after it executes this function. You must handle clearing the variable.

Expand image Remarks

Use this function or the RUN Function (Report) if you know at design time the exact report you want to run. Otherwise, use the REPORT.RUNMODAL Function or REPORT.RUN Function.

If the report you specify does not exist, a compile error occurs.

The request form is run modally when you use this function.

Expand image Example

This example requires that you create the following variables.

Variable name | DataType | Subtype
CustomerRec | Record | Customer
SomeReport | Report | Chart of Accounts
CopyCode image Copy Code
…
CLEAR(CustomerRec);
CustomerRec.SETRECFILTER;
SomeReport.XXX; // Any user-defined function.
SomeReport.SETTABLEVIEW(CustomerRec);
SomeReport.RUNMODAL()

Expand image See Also

Reference

Report Data Type


SAVEASEXCEL Function (Report)

SAVEASEXCEL Function (Report)
See Also
CollapseAll image

Saves a report as a Microsoft Office Excel file.

[Ok :=] Report.SAVEASEXCEL(Number, FileName[, Record])
[Ok :=] Report.SAVEASEXCEL(FileName)

Parameters

Number

Type: Integer

The ID of the report that you want to run. You can click View, and then click C/AL Symbol Menu to select the report from a list.

If the report you specify does not exist, a run-time error occurs.

FileName

Type: Text

The path to and the name of the file that you want to save the report as.

Record

Type: Record

Specifies which record to use in the report. Any filters that have been applied to the record that you specify will be used.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, then run-time errors can occur. If you include a return value, then it is assumed that you will handle any errors.

true if the report was saved; otherwise, false.

Expand image Remarks

The SAVEASEXCEL function can be used on the Report type and on Report variables. This function is supported only on client report definition (RDLC) layouts. If you delete the RDLC layout and then run the SAVEASEXCEL function, then you get the following error:

The layout of this report has not been transformed to be viewed in the RoleTailored client. You can run this report from the Microsoft Dynamics NAV Classic client.

When you call the SAVEASEXCEL function, the report is generated and saved to "FileName." A Saving to Excel window shows the progress of the process. Note that the Request Form will not be shown.

Expand image See Also

Reference

Report Data Type


SAVEASHTML Function (Report)

SAVEASHTML Function (Report)
See Also
CollapseAll image

Saves a report as an HTML file. We recommend that you use a browser that supports at least HTML version 3.0 for viewing the file.

[Ok :=] Report.SAVEASHTML(Number, FileName [,SystemPrinter] [, Rec])
[Ok :=] Report.SAVEASHTML(FileName)

Parameters

Number

Type: Integer

The ID of the report that you want to run. On the View menu, click C/AL Symbol Menu to select the report from a list.

FileName

Type: Text

The path and name of the file that you want to save the report as.

Record

Type: Record

Specifies which record to use in the report. Any filters that have been applied to the record that you specify will be used.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, then a run-time error occurs if the record cannot be found. If you include a return value, then it is assumed that you will handle any errors.

true if the report was saved; otherwise, false.

Expand image Remarks

The SaveAsHTML function can be used on the Report type and on Report variables.

When SaveAsHTML is called, the report is generated and saved to "FileName." The Saving to HTML window is displayed and shows the status of the process. You can manually cancel the generation of the report and cancel saving the report as an HTML file. The Request Form is not shown.

The return value indicates whether the report has been saved successfully. If you use this value and an error occurs, then false is returned. If you do not use the return value, then an error results in an error message such as "Out of hard disk space," "The file parameter is not open," "The user cancelled from the Save As HTML box," and so on. The object is closed.

This function is not supported on the computer running Microsoft Dynamics NAV Server. Therefore, if you run either a Classic report layout or a client report definition (RDLC) report layout from the RoleTailored client, then you cannot call the SAVEASHTML function. From the Classic client, the SAVEASHTML function is supported.

Expand image See Also

Reference

Report Data Type


SAVEASPDF Function (Report)

SAVEASPDF Function (Report)
See Also
CollapseAll image

Saves a report as a .pdf file.

[Ok :=] Report.SAVEASPDF(Number, FileName[, Record])
[Ok :=] Report.SAVEASPDF(FileName)

Parameters

Number

Type: Integer

The ID of the report that you want to run. On the View menu, click C/AL Symbol Menu to select the report from a list.

FileName

Type: Text

The path and name of the file that you want to save the report as.

Record

Type: Record

Specifies which record to use in the report. Any filters that have been applied to the record that you specify will be used.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, then run-time errors can occur. If you include a return value, it is assumed that you will handle any errors.

true if the report was saved; otherwise, false.

Expand image Remarks

The SaveAsPDF function can be used on the Report type and on Report variables. This function is supported only on client report definition (RDLC) layouts. If you delete the RDLC layout and then run the SaveAsPDF function, then you get the following error:

The layout of this report has not been transformed to be viewed in the RoleTailored client. You can run this report from the Classic client.

When you call SaveAsPDF, the report is generated and saved to "FileName." A Saving to PDF window shows the status of the process. Note that the Request Form will not be shown.

The FileName parameter specifies a location on the computer running Microsoft Dynamics NAV Server. If you call this function from the RoleTailored client, such as from an action on a page, then use the DOWNLOAD Function (File) to download the .pdf file from the computer running Microsoft Dynamics NAV Server to the computer running the RoleTailored client.

Expand image See Also

Reference

Report Data Type


SAVEASXML Function (Report)

SAVEASXML Function (Report)
See Also
CollapseAll image

Saves a report as an .xml file.

[Ok :=] Report.SAVEASXML(Number, FileName [,SystemPrinter][,Rec])
[Ok :=] Report.SAVEASXML(FileName)

Parameters

Number

Type: Integer

The ID of the report that you want to run. On the View menu, click C/AL Symbol Menu to select the report from a list.

If the report that you specify does not exist, then a run-time error occurs.

FileName

Type: Text

The path and name of the file that you want to save the report as.

Record

Type: Record

Specifies which record to use in the report. Any filters that have been applied to the record that you specify will be used.

Expand image Property Value/Return Value

Type: Boolean

If you omit this optional return value, then a run-time error occurs if the record cannot be found. If you include a return value, then it is assumed that you will handle any errors.

true if the report was saved; otherwise, false.

Expand image Remarks

The SaveAsXML function can be used on the Report type and on Report variables.

When SaveAsXML is called, the report is generated and saved to "FileName." A Saving to XML window is displayed and shows the status of the process. If you click Cancel, then the report is not generated or saved as an .xml file. The Request Form is not shown.

The return value indicates whether the report has been saved successfully. If you use this value and an error occurs, then false is returned. If you do not use the return value, then the error results in an error message such as "Out of hard disk space," "The file parameter is not open," "The user cancelled from the Save As XML box," and so on. The object is then closed.

This function is not supported on the computer running Microsoft Dynamics NAV Server. Therefore, if you run either a Classic report layout or a client report definition (RDLC) report layout from the RoleTailored client, then you cannot call the SAVEASXML function. From the Classic client, the SAVEASXML function is supported.

Expand image See Also

Reference

Report Data Type


SHOWOUTPUT Function (Report)

SHOWOUTPUT Function (Report)
See Also Example
CollapseAll image

Returns the current setting of whether a section should be printed, and changes this setting.

[IsShow :=] SHOWOUTPUT([SetShow])

Parameters

SetShow

Type: Boolean

The new setting.

Specify true to mean that the section will be printed; otherwise, specify false.

Expand image Property Value/Return Value

Type: Boolean

true if the section is printed; otherwise, false.

Expand image Remarks

This function is typically used when there is more than one section of the same type and it must decided from the value of a field, for example, whether the section should be printed.

This function is not supported on client report definition (RDLC) report layouts.

Expand image Example

This example shows how to use the SHOWOUTPUT function in the OnPreSection Trigger of the section in order to print a section only when the field called Amount is different from 0.
CopyCode image Copy Code
CurrReport.SHOWOUTPUT(Amount <> 0);

Expand image See Also

Reference

Report Data Type


TOTALSCAUSEDBY Function (Report)

TOTALSCAUSEDBY Function (Report)
See Also Example
CollapseAll image

Determines which field caused a group total to be calculated. This determines which field changed contents and thereby concluded a group.

FieldNo := TOTALSCAUSEDBY

Expand image Property Value/Return Value

Type: Integer

The number of the field that caused the group to end and a group total to be calculated.

Expand image Remarks

This function can only be used in group header and group footer sections. It is useful when you have defined several levels of grouping and need to know which of the groups has changed and caused a group total to be calculated.

This function is not supported on client report definition (RDLC) report layouts.

Expand image Example

This example shows how to use the TOTALSCAUSEDBY function to design a report where you group records according to the contents of several fields and you do not want to print the group header section when the item number changes. Use the following C/AL code in the OnPreSection Trigger of the section. To view code in section triggers, on the View menu, click Sections, and then on the View menu, click C/AL Code.

This example requires that you create the following variable.

Name | Data type | Subtype
ItemRec | Record | Item
CopyCode image Copy Code
IF CurrReport.TOTALSCAUSEDBY = ItemRec.FIELDNO("No.") THEN
  CurrReport.SHOWOUTPUT(FALSE);

Expand image See Also

Reference

Report Data Type


URL Function (Report)

URL Function (Report)
CollapseAll image

Returns a string with the full URL to a report.

String := Report.URL([UseNames])

Parameters

Report

Type: Form or report or any subtype

The report variable.

UseNames

Type: Boolean

This parameter is optional. If it is set to true (default value) or if it is empty, the returned string contains references to field names in the table with which the record is associated. If the parameter is set to false, field numbers are used instead.

Expand image Property Value/Return Value

Type: Text or code

The string with the full URL to a report.

Expand image Remarks

This function is equivalent to the functionality in the menu item Copy Link.

For examples of how to format URLs, see Composing URLs.

If the URL links to a report with several tables and this function is run, only one view in the request form is shown, namely the primary table. The primary table is the first table shown in the request form.

This function is not support on client report definition (RDLC) report layouts.


USEREQUESTFORM Function (Report)

USEREQUESTFORM Function (Report)
See Also
CollapseAll image

Returns the current setting of the UseReqForm Property and sets this property to a new value.

[IsUseRequestForm :=] USEREQUESTFORM([SetUseRequestForm])

Parameters

SetUseRequestForm

Type: Boolean

The new setting of the UseReqForm Property.

Expand image Property Value/Return Value

Type: Boolean

The current setting of the UseReqForm Property.

Expand image Remarks

This function should be used before the request form is run in the OnInitReport Trigger. Although it will not cause an error if it is used elsewhere, it will have no effect.

Expand image See Also

Reference

UseReqForm Property
Report Data Type


Strings

Strings

This section contains the following topics:

  • BigText Data Type

  • Code Data Type

  • Text Data Type

  • BigText Functions

  • String Functions

We recommend the following guidelines for using the BigText, Code, and Text data types:

  • Use the BigText data type for large documents.

  • If a text field is part of a primary key, then use the Code data type.

  • If a text field has a TableRelation, then use the Code data type.

  • If the field is assigned values from a Code field, then use the Code data type. For example, if the Document No. field in the G/L Entry table is copied from the primary key field No. in the Sales Header or Purchase Header table, then use the Code data type for the Document No. field.

  • For all other text fields, use the Text data type.


BigText Data Type

BigText Data Type

This complex data type handles large text documents.

Expand image Remarks

This data type cannot be shown in a message window or be seen in the debugger.

The maximum length of a BigText variable is 2,147,483,647 characters and this corresponds to 2 GB.

You can use the BigText functions to manipulate a BigText variable, for example to extract part of a BigText variable or to add a text string to a BigText variable.

The normal string functions cannot be used with a BigText variable.

Expand image See Also

Reference

ADDTEXT Function (BigText)
GETSUBTEXT Function (BigText)
LENGTH Function (BigText)
READ Function (BigText)
TEXTPOS Function (BigText)
WRITE Function (BigText)


Code Data Type

Code Data Type
See Also Example
CollapseAll image

This simple data type denotes a special type of string that is converted to uppercase and removes any trailing or leading characters.

Expand image Remarks

The length of a Code variable equals the number of characters in the text without leading or trailing spaces.

The maximum length of a Code field in a table is 250 characters. The maximum length of a Code variable is 1024 characters.

A Code variable cannot be null.

You can index any character position in a string, such as A[65]. The resulting value will be a Char Data Type.

Fields that contain a date formula must not have data type Code. Instead, use the DateFormula Data Type. All fields that contain a date formula with data type Code must be converted into data type DateFormula.

Differences Between the Classic Client and RoleTailored Client

In the RoleTailored client, you cannot assign a char to a position in the code variable greater than the current length of the variable +1. For more information, see Char Data Type.

Expand image Example

This example shows some typical examples of code string assignments. In these examples, assume that the variable c is a code variable with a maximum length of 4.
CopyCode image Copy Code
c := 'ABC';
// Results in variable c, which contains 'ABC'
// and is 3 characters in length.
c := '1';
// Results in variable c, which contains '1'
// and is 1 character in length.
c := '';
// Results in variable c, which contains '' (empty string)
// and is zero (0) characters in length.
c := ' 2 ';
// Results in variable c, which contains '2'
// and is 1 character in length.

Expand image See Also

Reference

CONVERTSTR Function (Code, Text)
COPYSTR Function (Code, Text)
DELCHR Function (Code, Text)
DELSTR Function (Code, Text)
FORMAT Function (Code, Text)
INCSTR Function (Code, Text)
INSSTR Function (Code, Text)
LOWERCASE Function (Code, Text)
MAXSTRLEN Function (Code, Text)
PADSTR Function (Code, Text)
SELECTSTR Function (Code, Text)
STRCHECKSUM Function (Code, Text)
STRLEN Function (Code, Text)
STRPOS Function (Code, Text)
STRSUBSTNO Function (Code, Text)
UPPERCASE Function (Code, Text)


Text Data Type

Text Data Type
See Also Example
CollapseAll image

This simple data type denotes a text string.

Expand image Remarks

The maximum length of a Text variable is 1024 characters. The maximum length of a Text field in a table is 250 characters. The length of a text variable equals the number of characters in the string. An empty text string has a length of zero (0). A text string cannot be null.

You can index any character position in a text string, for example A[65]. The resulting value will be a Char Data Type.

Differences Between the Classic Client and RoleTailored Client

In the RoleTailored client, you cannot assign a char to a position in the code variable greater than the current length of the variable +1. For more information, see Char Data Type.

Expand image Example

This example shows some typical examples of text strings. In these examples, the text variable has a maximum length of 6.
CopyCode image Copy Code
text := 'ABC';
// Results in a text variable which contains 'ABC'
text := '123456abc';
// Results in a run-time error because the length (9)
// exceeds the maximum length of 6.

Expand image See Also

Reference

CONVERTSTR Function (Code, Text)
COPYSTR Function (Code, Text)
DELCHR Function (Code, Text)
DELSTR Function (Code, Text)
FORMAT Function (Code, Text)
INCSTR Function (Code, Text)
INSSTR Function (Code, Text)
LOWERCASE Function (Code, Text)
MAXSTRLEN Function (Code, Text)
PADSTR Function (Code, Text)
SELECTSTR Function (Code, Text)
STRCHECKSUM Function (Code, Text)
STRLEN Function (Code, Text)
STRPOS Function (Code, Text)
STRSUBSTNO Function (Code, Text)
UPPERCASE Function (Code, Text)


BigText Functions

BigText Functions

This section contains the following topics:

  • ADDTEXT Function (BigText)

  • GETSUBTEXT Function (BigText)

  • LENGTH Function (BigText)

  • READ Function (BigText)

  • TEXTPOS Function (BigText)

  • WRITE Function (BigText)


ADDTEXT Function (BigText)

ADDTEXT Function (BigText)
See Also
CollapseAll image

Adds a text string to a BigText variable.

BigText.ADDTEXT(Variable[, Position])

Parameters

Variable

Type: Text or BigText

The string that will be added to the BigText variable. If this parameter is empty, then the BigText variable is not modified.

Position

Type: Integer

This is an optional parameter that defines the position in the BigText variable where the string is inserted. If this parameter is omitted, then the string is added at the end of the BigText variable. If this parameter is less than one, then a run-time error occurs. If this parameter is greater than the length of the BigText variable, then the string is added at the end of the BigText variable.

Expand image Remarks

Variable can be inserted anywhere in BigText or added at the end of the BigText.

The first character in a BigText variable is position 1.

To delete the content in a BigText variable use the CLEAR Function.

CopyCode image Copy Code
CLEAR(BigText)

The following table shows examples of the ADDTEXT function.

Initial BigText variable | Function call | Result
ABCDEFG | BigText.ADDTEXT('ZZZ', 0) | Error
ABCDEFG | BigText.ADDTEXT('ZZZ', 3) | ABZZZCDEFG
ABCDEFG | BigText.ADDTEXT('ZZZ', 15) | ABCDEFGZZZ
ABCDEFG | BigText.ADDTEXT('', 1) | ABCDEFG

Expand image See Also

Reference

BigText Data Type


GETSUBTEXT Function (BigText)

GETSUBTEXT Function (BigText)
See Also
CollapseAll image

Retrieves part of a BigText variable.

[RetLength :=] BigText.GETSUBTEXT(Variable, Position[, Length])

Parameters

Variable

Type: Text or BigText

The subtext of the BigText that is retrieved. This is the actual text that is returned.

Position

Type: Integer

The position in the BigText variable that the subtext is to be retrieved from. If this parameter is less than one, then a run-time error occurs. If this parameter is greater than the length of the BigText variable, then an empty string is returned. If the value of this parameter plus the value of the Length parameter is greater than the length of the BigText variable, then the remainder of the BigText variable from the position specified by this parameter is returned.

Length

Type: Integer

The length of the subtext that should be retrieved. This parameter is optional. If this parameter is omitted the function retrieves a subtext that starts at Position and runs to the end of the BigText variable. If this parameter is less than 0, then a run-time error occurs. If the value of the Position parameter plus the value of this parameter is greater than the length of the BigText variable, then the remainder of the BigText variable from the position specified by this parameter is returned.

Expand image Property Value/Return Value

Type: Integer

The length of the string that is retrieved from the variable.

Expand image Remarks

The first character in a BigText variable is position 1.

The following table shows examples of the GETSUBTEXT function.

Initial BigText variable | Function call | Result
ABCDEFG | BigText.GETSUBTEXT(MyVariable, 3, 2) | CD
ABCDEFG | BigText.GETSUBTEXT(MyVariable, 0, 4) | Error
ABCDEFG | BigText.GETSUBTEXT(MyVariable, 5, -2) | Error
ABCDEFG | BigText.GETSUBTEXT(MyVariable, 15, 4) | (empty string)
ABCDEFG | BigText.GETSUBTEXT(MyVariable, 4, 15) | DEFG

To delete the content in a BigText variable use the CLEAR Function.

CopyCode image Copy Code
CLEAR(BigText)

Expand image See Also

Reference

BigText Data Type


LENGTH Function (BigText)

LENGTH Function (BigText)
See Also
CollapseAll image

Retrieves the length of a BigText variable.

Length := BigText.LENGTH

Expand image Property Value/Return Value

Type: Integer

The length of the BigText variable.

Expand image Remarks

To delete the content in a BigText variable use the CLEAR function.

CopyCode image Copy Code
CLEAR(BigText)

Expand image See Also

Reference

BigText Data Type


READ Function (BigText)

READ Function (BigText)
See Also Example
CollapseAll image

Streams a BigText that is stored as a BLOB in a table to a BigText variable.

[Ok := ] BigText.READ(InStream)

Parameters

InStream

Type: InStream

The InStream object type to which you read a BigText.

Expand image Property Value/Return Value

Type: Boolean

This optional return value specifies whether the read transaction was successful.

Expand image Remarks

To delete the content in a BigText variable use the CLEAR function.

CopyCode image Copy Code
CLEAR(BigText)

Expand image Example

This example shows how to stream a BigText that is stored as a BLOB in a table to a BigText variable.

This example requires that you define the following variables.

Variable | DataType | Subtype
Bstr | BigText |
EmployeeRec | Record | Employee
Istream | InStream |
CopyCode image Copy Code
EmployeeRec.FIND('-');
EmployeeRec.CALCFIELDS(Picture);
EmployeeRec.Picture.CREATEINSTREAM(Istream);
Bstr.READ(Istream);

You use the CALCFIELDS Function (Record) to calculate the BlobField. A BlobField is a binary large object (maximum size 2 GB) and must be calculated if you want to use it in C/AL or display it in the application.

Expand image See Also

Reference

BigText Data Type


TEXTPOS Function (BigText)

TEXTPOS Function (BigText)
See Also
CollapseAll image

Retrieves the position at which a specific string first occurs in a BigText.

Position := BigText.TEXTPOS(String)

Parameters

String

Type: Text

The text string to search for in the BigText variable. If this parameter is empty, then 0 is returned.

Expand image Property Value/Return Value

Type: Integer

This return value indicates the position where the first occurrence of the string starts in the BigText variable.

If String is not found in the BigText variable, then 0 is returned.

Expand image Remarks

The first character in a BigText variable is position 1.

The following table shows examples of the TEXTPOS function.

BigText variable | Function call | Position returned
ABCDEFG | BigText.TEXTPOS("BCD"); | 2
ABCDEFG | BigText.TEXTPOS(""); | 0
ABCDEFG | BigText.TEXTPOS("XYZ"); | 0

To delete the content in a BigText variable use the CLEAR function.

CopyCode image Copy Code
CLEAR(BigText)

Expand image See Also

Reference

BigText Data Type


WRITE Function (BigText)

WRITE Function (BigText)
See Also Example
CollapseAll image

Streams a BigText to a BLOB field in a table.

[Ok := ] BigText.WRITE(OutStream)

Parameters

OutStream

Type: OutStream

The object to which you write a BigText.

Expand image Property Value/Return Value

Type: Boolean

This optional return value specifies whether the write transaction was successful.

Expand image Remarks

To delete the content in a BigText variable use the CLEAR function.

CopyCode image Copy Code
CLEAR(BigText)

Expand image Example

This example shows how to stream a BigText to a BLOB field in a table.

This example requires that you define the following variables.

Variable name | DataType | Subtype
Bstr | BigText |
ItemRec | Record | Item
Ostream | OutStream |
CopyCode image Copy Code
Bstr.ADDTEXT('This is the text string that we want to store in a BLOB field.');
ItemRec.Picture.CREATEOUTSTREAM(Ostream);
Bbstr.WRITE(Ostream);
ItemRec.INSERT;

Expand image See Also

Reference

BigText Data Type


String Functions

String Functions

This section contains the following topics:

  • CONVERTSTR Function (Code, Text)

  • COPYSTR Function (Code, Text)

  • DELCHR Function (Code, Text)

  • DELSTR Function (Code, Text)

  • FORMAT Function (Code, Text)

  • INCSTR Function (Code, Text)

  • INSSTR Function (Code, Text)

  • LOWERCASE Function (Code, Text)

  • MAXSTRLEN Function (Code, Text)

  • PADSTR Function (Code, Text)

  • SELECTSTR Function (Code, Text)

  • STRCHECKSUM Function (Code, Text)

  • STRLEN Function (Code, Text)

  • STRPOS Function (Code, Text)

  • STRSUBSTNO Function (Code, Text)

  • UPPERCASE Function (Code, Text)


CONVERTSTR Function (Code, Text)

CONVERTSTR Function (Code, Text)
See Also Example
CollapseAll image

Converts some characters in a string.

NewString := CONVERTSTR(String, FromCharacters, ToCharacters)

Parameters

String

Type: Text constant or code

The string that you want to convert.

FromCharacters

Type: Text constant or code

The characters that you want to replace. This function is case-sensitive.

ToCharacters

Type: Text constant or code

The new characters you want to insert. This function is case-sensitive.

The length of this string must correspond to the length of FromCharacters.

Expand image Property Value/Return Value

Type: Text constant or code

The converted string.

Expand image Remarks

The characters in the FromCharacters parameter are replaced by the characters in the ToCharacters parameter.

A run-time error occurs if the lengths of the FromCharacters and ToCharacters strings are not equal.

If either the FromCharacters or the ToCharacters strings are empty the source is returned unchanged.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
OriginalString | Text | 30
FromChars | Text | 30
ToChars | Text | 30
NewString | Text | 30
Text constant | ENU value
Text000 | Do you want to leave without saving?
Text001 | lws
Text002 | LWS
Text003 | The original sentence is:\ %1
Text004 | The sentence is converted to:\ %1
CopyCode image Copy Code
OriginalString := Text000;
FromChars := Text001;
ToChars := Text002;
NewString := CONVERTSTR(OriginalString, FromChars, ToChars);
MESSAGE(Text003, OriginalString);
MESSAGE(Text004, NewString);

The first message window shows:

The original sentence is:

Do you want to leave without saving?

The second message window shows:

The sentence is converted to:

Do you Want to Leave Without Saving?

Expand image See Also

Reference

Code Data Type
Text Data Type


COPYSTR Function (Code, Text)

COPYSTR Function (Code, Text)
See Also Example
CollapseAll image

Copies a substring of any length from a specific position in a string (text or code) to a new string.

NewString := COPYSTR(String, Position[, Length])

Parameters

String

Type: Text constant or code

The string that you want to copy from.

Position

Type: Integer

The position of the first character to copy. The value of Position must be greater than zero (0). If Position is greater than the length of the string, the system returns an empty string.

Length

Type: Integer

The number of characters to copy. Length must be greater than zero (0). If the value of Length results in Position + Length > (total length of the string), then the result includes all the characters from Position to the end of the string.

Expand image Property Value/Return Value

Type: Text constant or code

The resulting string or substring

Expand image Remarks

If you omit Length, the resulting string includes all the characters from Position to the end of the string.

If Position is less than 1 or Length is less than 0, an error is returned.

If Position is beyond the length of the current string, an empty string is returned.

If Position combined with Length exceeds the length of the string, all the characters from Position to the end of the string are returned.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
Str | Text | 30
Position | Integer |
Length | Integer |
NewStr | Text | 30
Text constant | ENU value
Text000 | Using the COPYSTR function
Text001 | The original string is:\>%1<
Text002 | The copied string is:\>%1<
CopyCode image Copy Code
Str := Text000;
Position := 7;
Length := 8;
MESSAGE(Text001, Str);
NewStr := COPYSTR(Str, Position, Length);
MESSAGE(Text002, NewStr);

The first message window shows the original string:

The original string is:

>Using the COPYSTR function<

The second message window shows the copied string:

The copied string is:

>the COPY<

Expand image See Also

Reference

Code Data Type
Text Data Type


DELCHR Function (Code, Text)

DELCHR Function (Code, Text)
See Also Example
CollapseAll image

Deletes one or more characters in a string.

NewString := DELCHR(String[, Where][, Which])

Parameters

String

Type: Text constant or code

The input string.

Where

Type: Text constant or code

Specifies where to delete characters.

You can include one or more of the following characters in the Where string:

  • = To delete any character in String that matches a character in Which (default)

  • < To delete any leading character in String that matches a character in Which

  • > To delete any trailing character in String that matches a character in Which

Which

Type: Text or code

Specifies the characters that you want to delete.

The default is a space character.

Expand image Property Value/Return Value

Type: Text constant or code

The resulting string.

Expand image Remarks

The DELCHR function is case-sensitive.

If you omit the Which parameter, then the function deletes spaces from String based on the contents of the Where parameter as follows:

  • If Where contains =, then all the spaces are deleted from String.

  • If Where contains <, then all the spaces at the beginning of String are deleted.

  • If Where contains >, then all the spaces at the end of String are deleted.

  • If Where contains any other character, then an error is returned.

  • If Where is empty, then String is returned unchanged.

If you use the Where and the Which parameters, the function deletes from String the characters contained in the Which parameter based on the contents of the Where parameter as follows:

  • If Where contains =, then every occurrence of the characters in Which are deleted from String.

  • If Where contains <, then the characters in Which are only deleted if they occur at the beginning of String.

  • If Where contains >, then the characters in Which are only deleted if they occur at the end of String.

  • If Where contains any other character, then an error is returned.

  • If Where is empty, then String is returned unchanged.

  • If Which is empty, then String is returned unchanged.

The Which parameter contains an array of the characters that you want to delete. The order of the characters is of no significance. If String contains a character that is specified in Which, it is deleted from String.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
String | Text | 30
Where | Text | 30
Which | Text | 30
NewString | Text | 30
Text constant | ENU value
Text000 | Windy West Solutions
Text001 | >%1< is transformed to >%2<
CopyCode image Copy Code
String := Text000;
Where := '<>';
Which := 'Ws';
NewString := DELCHR(String, Where, Which);
MESSAGE(Text001, String,NewString);

The message window displays the following:

>Windy West Solutions< is transformed to >indy West Solution<

The function deletes every W and s that is either the first or last character in String.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
String | Text | 30
Where | Text | 30
Which | Text | 30
NewString | Text | 30
Text constant | ENU value
Text000 | This is an example
Text001 | >%1< is transformed to >%2<
CopyCode image Copy Code
String := Text000;
Where := '=';
Which := 'sx';
NewString := DELCHR(String, Where, Which);
MESSAGE(Text001, String,NewString);

The message window displays the following:

>This is an example< is transformed to >Thi i an eample<

The function deletes every s and x from String.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
String | Text | 30
Where | Text | 30
Which | Text | 30
NewString | Text | 30
Text constant | ENU value
Text000 | This is an example
Text001 | >%1< is transformed to >%2<
CopyCode image Copy Code
String := Text000;
Where := '>';
Which := 'Tely';
NewString := DELCHR(String, Where, Which);
MESSAGE(Text001, String,NewString);

The message window displays the following:

>This is an example< is transformed to >This is an examp<

If T, e, l, or y is the last character in String, the function deletes them.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
String | Text | 30
Where | Text | 30
Which | Text | 30
NewString | Text | 30
Text constant | ENU value
Text000 | This is an example
Text001 | >%1< is transformed to >%2<
CopyCode image Copy Code
String := Text000;
Where := '<';
Which := 'Thsi ';
NewString := DELCHR(String, Where, Which);
MESSAGE(Text001, String,NewString);

The message window displays the following:

>This is an example<, is transformed to: > an example<

If T, h, s, i, or space is the first character in String, the function deletes them.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
String | Text | 30
Where | Text | 30
Which | Text | 30
NewString | Text | 30
Text constant | ENU value
Text000 | This is an example
Text001 | >%1< is transformed to >%2<
CopyCode image Copy Code
String := Text000;
Where := '<';
NewString := DELCHR(String, Where);
MESSAGE(Text001, String,NewString);

The message window displays the following:

> This is an example< is transformed to >This is an example<

The function removes any spaces from the beginning of String.

Expand image See Also

Reference

Code Data Type
Text Data Type


DELSTR Function (Code, Text)

DELSTR Function (Code, Text)
See Also Example
CollapseAll image

Deletes a substring inside a string (text or code).

NewString := DELSTR(String, Position[, Length])

Parameters

String

Type: Text constant or code

The input string.

Position

Type: Integer

The position of the first character that you want to delete. Position must be greater than zero (0).

If Position exceeds the length of String, DELSTR returns the original string, unchanged.

Length

Type: Integer

Specifies how many characters to delete. Length must be greater than zero (0).

Expand image Property Value/Return Value

Type: Text constant or code

The resulting string.

Expand image Remarks

If you omit Length, all the characters starting with Position are deleted until the end of the string.

If you omit Length and Position is less than 1, then an error is returned.

If you omit Length and Position is greater than the length of String, then String is returned unchanged.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
Str | Text | 30
Position | Integer |
Length | Integer |
NewStr | Text | 30
Text constant | ENU value
Text000 | Adjusting prices - Please wait.
Text001 | The original string:\>%1<
Text002 | The modified string:\>%2<
CopyCode image Copy Code
Str := Text000;
Position := 11; // Remove the word 'prices' and a blank
Length := 7;
NewStr := DELSTR(Str, Position, Length);
MESSAGE(Text001, Str);
MESSAGE(Text002, NewStr);

The first message window displays the following:

The original string:

>Adjusting prices - Please wait.<

The second message window displays the following:

The modified string:

>Adjusting - Please wait.<

Expand image See Also

Reference

Code Data Type
Text Data Type


FORMAT Function (Code, Text)

FORMAT Function (Code, Text)
See Also Example
CollapseAll image

Formats a value into a string.

String := FORMAT(Value[, Length][, FormatStr/FormatNumber])

Parameters

Value

Type: Any

This is a C/AL variable (expression) of any simple data type, such as option, integer, biginteger, decimal, char, text, code, date, time, datetime, Boolean, binary, or GUID.

If, when the system formats Value, the result is a value larger than the maximum length MAXSTRLEN Function (Code, Text) of String, a run-time error occurs.

Length

Type: Integer

This optional parameter specifies the length of String. The following rules apply:

  • If Length = 0 then the entire value is returned (default).

  • If Length > 0 then the returned string will be exactly Length characters.

    If Value is less than Length characters, then either leading or trailing spaces are inserted, depending on the format that you select.

    If Value exceeds Length characters, then String is truncated to Length characters.

  • If Length < 0 then the returned string will not have leading or trailing spaces.

    If Value is less than Length characters, the length of String will equal the length of Value.

    If Value exceeds Length characters, then String is truncated to Length characters.

FormatStr

Type: String

A literal string that defines a format as in the Format Property.

FormatNumber

Type: Integer

This optional parameter specifies the format that you want to use. The basic options are the following:

  • <Sign><Integer Thousand><Decimals> is Format 0

  • <Sign><Integer><Decimals> is Format 1

  • <Sign><Integer><Decimals><1000Character,.> is Format 2

  • <Integer Thousand><Decimals><Sign,1> is Format 3

  • <Integer><Decimals><Sign,1> is Format 4

Note Note

You cannot use both FormatNumber and FormatStr at the same time.

Expand image Property Value/Return Value

Type: Text or code

The formatted output string.

Expand image Remarks

For more information about the formats used by the various data type, see the Format Property. This topic describes the various predefined formats in detail, and how to create customized formats.

Format 9 is designed to be used when importing data with an XMLport and has only one function to convert the data from XML format to the corresponding C/SIDE formats.

Expand image Example

This example requires that you create the following text constant in the C/AL Globals window.

Text constant | ENU value
Text000 | The formatted value: >%1<
CopyCode image Copy Code
MESSAGE(Text000, FORMAT(-123456.78, 15, 3));

The message window displays the following:

The formatted value: > 123,456.78-

This example shows how to use a string to build a format.

This example requires that you create the following text constant in the C/AL Globals window.

Text constant | ENU value
Text000 | Today is %1.
CopyCode image Copy Code
MESSAGE(Text000, FORMAT(TODAY,0,'<Month Text> <Day>'));

The message window displays the following:

Today is April 15.

Expand image See Also

Reference

Code Data Type
Text Data Type


INCSTR Function (Code, Text)

INCSTR Function (Code, Text)
See Also Example
CollapseAll image

Increases a positive number or decrease a negative number inside a string by one (1).

NewString := INCSTR(String)

Parameters

String

Type: Text constant or code

The string that you want to increase or decrease.

Expand image Property Value/Return Value

Type: Text constant or code

The result after increasing or decreasing String.

Expand image Remarks

If String contains more than one number, only the number closest to the end of the string is changed. For example, 'A10B20' is changed to 'A10B21' and 'a12b12c' to 'a12b13c'.

If String contains a negative number, it is decreased by one. For example, '-55' is changed to '-56'.

Zero (0) is considered a positive number, so it is increased it by one. For example, 'A0' is changed to 'A1'.

When String contains a number such as 99, it is increased to 100 and the length of the output string is: LEN(String) + 1. For example, 'a12b99c' is changed to 'a12b100c'.

If String does not contain any number, the output string is an empty string. For example, 'aaa' is changed to ''.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
Account | Text | 60
NegAccount | Text | 60
MyAccount | Text | 60
ResAccount | Text | 60
ResNegAccount | Text | 60
ResMyAccount | Text | 60
Text constant | ENU value
Text000 | Account no. 99 does not balance.
Text001 | Account no.2342 shows a total of $-452.
Text002 | My bank account shows a total of $0.
Text003 | The text strings before INCSTR is called:\%1\%2\%3
Text004 | The text strings after INCSTR is called:\%1\%2\%3
CopyCode image Copy Code
Account := Text000;
NegAccount := Text001;
MyAccount := Text002;
MESSAGE(Text003, Account, NegAccount, MyAccount);
ResAccount := INCSTR(Account);
ResNegAccount := INCSTR(NegAccount);
ResMyAccount := INCSTR(MyAccount);
MESSAGE(Text004, ResAccount, ResNegAccount, ResMyAccount);

The first message displays the following:

The text strings before INCSTR is called:

Account no. 99 does not balance.

Account no. 2342 shows a total of $ -452.

My bank account shows a total of $ 0.

The second message displays the following:

The text strings after INCSTR has been called:

Account no. 100 does not balance.

Account no. 2342 shows a total of $ -453.

My bank account shows a total of $ 1.

The example shows that if the string contains more than one number, only the last number is changed. Furthermore, positive numbers and zero are increased and negative numbers are decreased.

Expand image See Also

Reference

Code Data Type
Text Data Type


INSSTR Function (Code, Text)

INSSTR Function (Code, Text)
See Also Example
CollapseAll image

Inserts a substring into a string.

NewString := INSSTR(String, SubString, Position)

Parameters

String

Type: Text constant or code

The string into which you want to insert a substring.

SubString

Type: Text constant or code

The substring that you want to insert into String.

Position

Type: Integer

Specifies where to insert SubString. Position must be greater than or equal to 1.

If Position is greater than the length of String, the result is concatenated and placed into NewString.

Expand image Property Value/Return Value

Type: Text constant or code

The result after inserting SubString into String.

Expand image Remarks

If SubString is empty, then String is returned unchanged.

If Position is less than 1, an error is returned.

If Position is greater than the length of String, SubString is added at the end of String. For example, INSSTR("Thomas","AAA",999) returns 'ThomasAAA'.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
Str | Text | 60
SubString | Text | 60
NewString | Text | 60
Text constant | ENU value
Text000 | Press ENTER to continue.
Text001 | or ESC
Text002 | The test string before INSSTR is called:\>%1<
Text003 | The resulting string after INSSTR is called:\>%1<
CopyCode image Copy Code
Str := Text000;
SubString := Text001;
MESSAGE(Text002, Str);
NewString := INSSTR(Str, SubString, 13);
MESSAGE(Text003, NewString);

The first message window displays the following:

The test string before INSSTR is called:

>Press ENTER to continue.<

The second message window displays the following:

The resulting string after INSSTR is called:

>Press ENTER or ESC to continue.<

Expand image See Also

Reference

Code Data Type
Text Data Type


LOWERCASE Function (Code, Text)

LOWERCASE Function (Code, Text)
See Also Example
CollapseAll image

Converts all letters in a string to lowercase.

NewString := LOWERCASE(String)

Parameters

String

Type: Text constant or code

The string that you want to convert to lowercase. Only letters in the range A to Z and if applicable, special language characters, are converted.

Expand image Property Value/Return Value

Type: Text constant or code

The resulting string after it has been converted to lowercase.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
Str | Text | 60
Lower | Text | 60
Text constant | ENU value
Text000 | The Entries are Sorted by Name.
Text001 | The string before LOWERCASE is:\>%1<
Text002 | The string after LOWERCASE is:\>%1<
CopyCode image Copy Code
Str := Text000;
MESSAGE(Text001, Str);
Lower := LOWERCASE(Str);
MESSAGE(Text002, Lower);

The first message window displays the following:

The string before LOWERCASE is:

>The Entries are Sorted by Name.<

The second message window displays the following:

The string after LOWERCASE is:

>the entries are sorted by name.<

Expand image See Also

Reference

Code Data Type
Text Data Type


MAXSTRLEN Function (Code, Text)

MAXSTRLEN Function (Code, Text)
See Also Example
CollapseAll image

Returns the maximum defined length of a string variable.

MaxLength := MAXSTRLEN(String)

Parameters

String

Type: Text constant or code

The string variable for which you want to find the maximum length.

Expand image Property Value/Return Value

Type: Integer

The maximum length of the string variable.

Expand image Remarks

If you call this function on a Variant, it returns an error.

Expand image Example

This example shows how to use the MAXSTRLEN function. Assume that City has been defined as a text variable with a maximum length of 30.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
City | Text | 30
MaxLength | Integer |
Length | Integer |
Text constant | ENU value
Text000 | Vedbaek
Text001 | The MAXSTRLEN function returns %1,\
Text002 | while the STRLEN function returns %2
CopyCode image Copy Code
City := Text000;
MaxLength := MAXSTRLEN(City);
Length := STRLEN(City);
MESSAGE(Text001 + Text002, MaxLength, Length);

The message window displays the following:

The MAXSTRLEN function returns 30,

while the STRLEN function returns 7.

Expand image See Also

Reference

Code Data Type
Text Data Type


PADSTR Function (Code, Text)

PADSTR Function (Code, Text)
See Also Example
CollapseAll image

Changes the length of a string to a length that you define.

NewString := PADSTR(String, Length[, FillCharacter])

Parameters

String

Type: Text constant or code

The string that you want to increase or decrease.

Length

Type: Integer

The desired length of the output string.

If Length is less than the length of String, then String is truncated. Otherwise String is expanded with filler characters.

If Length is less than 0, then an error is returned.

FillCharacter

Type: Text constant or code

This is a string of length 1. This character is used to fill empty spaces at the end of the output string. If not specified, spaces are used as default. If the length of FillCharacter is not 1, an error is returned.

Expand image Property Value/Return Value

Type: Text constant or code

The output string. The length of the return value is Length characters. If the maximum (defined) length of NewString is less than Length, a run-time error occurs.

Expand image Remarks

If you omit FillCharacter and String is shorter than Length, then spaces are added at the end of String to match Length.

If you omit FillCharacter and String is longer than Length, then String is truncated.

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
Str1 | Text | 30
Str2 | Text | 30
Len1 | Integer |
Len2 | Integer |
Text constant | ENU value
Text000 | 13 characters
Text001 | Four
Text002 | Before PADSTR is called:\
Text003 | >%1< has the length %2\
Text004 | >%3< has the length %4\
Text005 | After PADSTR is called:\
CopyCode image Copy Code
Str1 := Text000;
Str2 := Text001;
Len1 := STRLEN(Str1);
Len2 := STRLEN(Str2);
MESSAGE(Text002 + Text003 + Text004, Str1, Len1, Str2, Len2);
Str1 := PADSTR(Str1, 5); // Truncate the length to 5
Str2 := PADSTR(Str2, 15, 'w'); // Concatenate w until length = 15
Len1 := STRLEN(Str1);
Len2 := STRLEN(Str2);
MESSAGE(Text005 + Text003 + Text004, Str1, Len1, Str2, Len2);

The first message window displays the following:

Before PADSTR is called:

>13 characters< has the length 13

>Four< has the length 4

The second message window displays the following:

After PADSTR is called:

>13 ch< has the length 5

>Fourwwwwwwwwwww< has the length 15

Expand image See Also

Reference

Code Data Type
Text Data Type


SELECTSTR Function (Code, Text)

SELECTSTR Function (Code, Text)
See Also Example
CollapseAll image

Retrieves a substring from a comma-separated string.

NewString := SELECTSTR(Number, CommaString)

Parameters

Number

Type: Integer

Specifies which substring to retrieve. The substrings in the comma-separated string are numbered 1, 2, 3, and so on.

If Number is greater than the actual number of substrings, then a run-time error occurs.

CommaString

Type: Option

A string containing substrings separated by commas. The maximum length of this string is 391 characters.

Expand image Property Value/Return Value

Type: Option

The substring that is retrieved from CommaString.

Expand image Remarks

SELECTSTR treats string values as OPTIONS. This means that identical values in different strings are not allowed.

Any trailing commas are removed before the operation begins.

If Number is less than 1 or greater than the number of real values (excluding trailing commas) in the string, then an error is returned.

Quotes are not supported. For example, a,b,"c,d",e is treated as a five-element substring where substring 4 is d".

Expand image Example

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CommaStr | Text | 60
CommaStr2 | Text | 60
SubStr1 | Text | 60
SubStr2 | Text | 60
SubStr3 | Text | 60
SubStr4 | Text | 60
Text constant | ENU value
Text000 | This,is a comma,separated,string
Text001 | The calls to SELECTSTR return:\
Text002 | 11,22,33,,55,,,
CopyCode image Copy Code
CommaStr := Text000;
CommaStr2 := Text002;
SubStr1 := SELECTSTR(2, CommaStr); // Pick out the 2nd substring
SubStr2 := SELECTSTR(4, CommaStr); // Pick out the 4th substring
SubStr3 := SELECTSTR(1, CommaStr2);
SubStr4 := SELECTSTR(3, CommaStr2);
MESSAGE(Text001 + '>%1<\' + '>%2<\' + '>%3<\' + '>%4<\', SubStr1, SubStr2, SubStr3, SubStr4);

The message window displays the following text:

The calls to SELECTSTR return:

>is a comma<

>string<

>11<

>33<

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Subtype
CommaStr2 | Text | 60
SubStr5 | Text | 60
Text constant | ENU value
Text002 | 11,22,33,,55,,,
CopyCode image Copy Code
CommaStr2 := Text002;
SubStr5 := SELECTSTR(6,CommaStr2);
MESSAGE('>%1<\', SubStr5);

This example returns an error.

Expand image See Also

Reference

Code Data Type
Text Data Type


STRCHECKSUM Function (Code, Text)

STRCHECKSUM Function (Code, Text)
See Also Example
CollapseAll image

Calculates a checksum for a string that contains a number.

CheckNumber :=STRCHECKSUM(String[, WeightString][, Modulus])

Parameters

String

Type: Text constant or code

This string contains the number for which you want to calculate a checksum. You can only enter the numeric characters 0-9 in this string. If you entering anything else, a run-time error will occur. If String is empty, 0 is returned.

WeightString

Type: Text constant or code

This string contains numbers that you want to use as weights when calculating the checksum. The default value is a string containing STRLEN(String) '1'-characters.

You can only enter the numeric characters 0-9 in this string. If you enter anything else, a run-time error will occur.

If String is longer than WeightString, a string will be concatenated that contains STRLEN(String) - STRLEN(WeightString) '1'-characters to the end of WeightString. If WeightString is longer than String, a run-time error occurs.

Modulus

Type: Integer

The number that you want to use in the checksum formula. The default value is 10.

Expand image Property Value/Return Value

Type: Integer

The checksum, which is calculated using this formula:

Expand image Example

This example shows how to use the STRCHECKSUM function to calculate a checksum.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
StrNumber | Text | 30
Weight | Text | 30
Modulus | Integer |
Text constant | ENU value
Text000 | The number: %1\
Text001 | has the checksum: %2
CopyCode image Copy Code
StrNumber := '4378';
Weight := '1234';
Modulus := 7;
CheckSum := STRCHECKSUM(StrNumber, Weight, Modulus);
MESSAGE(Text000 + Text001, StrNumber, CheckSum);

The formula is:

(7 - (4x1 + 3x2 + 7x3 + 8x4) MOD 7) MOD 7=0

The message window displays the following:

The number: 4378

has the checksum: 0

This example shows how to use the STRCHECKSUM function to calculate a modulus 10 checksum for a bar code.

The STRCHECKSUM function can be used to calculate checksums for 13- and 8-digit European Article Number (EAN) and EAN-compatible bar codes such as a Universal Product Code (UPC) or Japanese Article Number (JAN).

A 13-digit EAN code has the following format:

  1. The 12 digits in positions 13 to 2 are used to calculate the checksum at position 1.

  2. Starting with position 2, all even values are totaled. The result is then multiplied by three. This value is called Even.

  3. Starting with position 3, all odd values are totaled. The result is called Odd.

  4. Total=Even + Odd.

  5. The modulus 10 checksum is then (10 - Total MOD 10) MOD 10.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | DataType | Length
StrNumber | Text | 30
Weight | Text | 30
Modulus | Integer |
Text constant | ENU value
Text000 | 'The EAN code: %1\'
Text001 | 'has the checksum: %2'
CopyCode image Copy Code
StrNumber := '577622135746';
Weight := '131313131313';
CheckSum := STRCHECKSUM(StrNumber, Weight);
MESSAGE(Text000 + Text001, StrNumber, CheckSum);

The message window displays the following:

The EAN code: 577622135746

has the checksum: 3

Expand image See Also

Reference

Code Data Type
Text Data Type


STRLEN Function (Code, Text)

STRLEN Function (Code, Text)
See Also Example
CollapseAll image

Returns the length of a string you define.

Length := STRLEN(String)

Parameters

String

Type: Text constant or code

The string for which you want to determine the length.

Expand image Property Value/Return Value

Type: Integer

The length of String.

Expand image Remarks

The difference between the STRLEN function and the MAXSTRLEN Function (Code, Text) is that the STRLEN returns the actual number of characters in the input string, while MAXSTRLEN returns the maximum defined length of the input string.

If you call STRLEN on a Variant, 0 is returned.

Expand image Example

This example shows the difference between the STRLEN and the MAXSTRLEN functions. Assume the variable City was defined with a maximum length of 30 characters.

This example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text000 | 'Atlanta'
Text001 | 'The MAXSTRLEN function returns: %1,\'
Text002 | 'while the STRLEN function returns: %2'
CopyCode image Copy Code
City := Text000;
MaxLength := MAXSTRLEN(City)
Length := STRLEN(City);
MESSAGE(Text001 + Text002, MaxLength, Length);

The message window displays the following:

The MAXSTRLEN function returns: 30

while the STRLEN function returns: 7

This shows that the MAXLENGTH function returns the maximum possible length according to the definition of the string variable, while STRLEN returns the actual length of the text.

Expand image See Also

Reference

Code Data Type
Text Data Type


STRPOS Function (Code, Text)

STRPOS Function (Code, Text)
See Also Example
CollapseAll image

Searches for the first occurrence of substring inside a string.

Position := STRPOS(String, SubString)

Parameters

String

Type: Text constant or code

The string in which you want to search.

SubString

Type: Text constant or code

The substring for which you want to search.

The STRPOS function is case-sensitive.

Expand image Property Value/Return Value

Type: Integer

The position of SubString in String.

Expand image Remarks

The STRPOS function returns the position of the first occurrence of the substring.

If SubString cannot be found, then the function returns zero.

If String or SubString is empty, then the function returns zero.

Expand image Example

This example shows how to use the STRPOS function.

This example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text000 | 'ABC abc abc xy'
Text001 | 'abc'
Text002 | 'The search for the substring: >%1<\'
Text003 | 'in the string: >%2<,\'
Text004 | 'returns the position: %3'
CopyCode image Copy Code
String := Text000;
SubStr := Text001
Pos := STRPOS(String, SubStr);
MESSAGE(Text002 + Text003 + Text004, SubStr, String, Pos);
// The STRPOS function is case-sensitive. Furthermore, it only
// returns the position of the 1st occurrence of the substring.

The message window displays the following:

The search for the substring: >abc<

in the string: >ABC abc abc xy<

returns the position: 5

CopyCode image Copy Code
Pos1 := StrPos("abc",""); //returns 0
Pos2 := StrPos("abc","c"); //returns 3
Pos3 := StrPos("abc","bc"); //returns 2
Pos4 := StrPos("abc","x"); //returns 0

Expand image See Also

Reference

Code Data Type
Text Data Type


STRSUBSTNO Function (Code, Text)

STRSUBSTNO Function (Code, Text)
See Also Example
CollapseAll image

Replaces %1, %2, %3... and #1, #2, #3... fields in a string with the values you provide as optional parameters.

NewString := STRSUBSTNO(String [,Value1, …])

Parameters

String

Type: Text constant or Code

A string containing '#' and/or '%' fields.

The % fields are replaced by the values with their full lengths, and # fields are replaced by the values that are truncated to the length of the # field.

If this parameter is an expression that evaluates to Text or Code that is 512 or more characters, then a run-time error occurs.

Value1, …

Type: Any

One or more values (expressions) that you want to insert into String. You can specify up to 10 values.

Expand image Property Value/Return Value

Type: Text constant or Code

The resulting string, after the corresponding values have been substituted into the '#' and '%' fields.

Expand image Remarks

This function replaces the numbered specifiers in a string with a string representation of the equivalent numbered value.

The specifiers in the string can be either %n or #######n, where n represents a 1-based number. When you use the # specifier, the number can be anywhere in the specifier. For example, ###2#### is allowed.

The %n specifier is replaced with the string representation of the value with their full lengths.

The ##n specifier is replaced with the same number of characters as the length of the specifier (including the number). The values are truncated to the length of the # field.

If the string representation is shorter than the length of the specifier, then it is left aligned.

For example, StrSubstNo('Test %1 >#2##< >#3<', 1,2,3) returns "Test 1 >2 < >3 <".

In this example, the following substitutions are made:

  • %1 is replaced by '1' because a % field is replaced by the specified value in its full length.

  • '#2##' is replaced by '2 space space space' because the value is shorter than the field and therefore, the 2 is left aligned and the field is four characters long.

  • #3 is replaced by '3 space' because the 3 is left aligned and the field is two characters long

If the string is longer, then asterisks are inserted to indicate overflow.

For example, StrSubstNo('Test %1 >###2< >#3<', 'Thomas','Thomas',0) returns "Test Thomas >****< >0 <".

In this example the following substitutions are made:

  • %1 is replaced by 'Thomas' because a %1 field is replaced by the specified value in its full length.

  • '###2' is replaced by '****' because the string 'Thomas' is longer than the ###2 field. Each character in the field is replaced by an asterisk.

  • #3 is replaced by '0 space' because the 0 is left aligned and the field is two characters long.

You can have several references to the same value.

For example, StrSubstNo('Test %1 %3 %1', 555, 666, 777) returns "Test 555 777 555".

If one of the values is null, then it is treated as an empty string.

For more information about the STRSUBSTNO function in a multilanguage-enabled application, see Developing Multilanguage-Enabled Applications.

Expand image Example

The following example shows how to use the STRSUBSTNO function.

This example requires that you create the following variables and text constants in the C/AL Globals window.

Variable name | Data type | Length
Str | Text | 1024
AccountNo | Integer |
Balance | Decimal |
Text constant | ENU value
Text000 | The balance of account %1 is $ %2
Text001 | The string before STRSUBSTNO has been called:\%1
Text002 | The string after STRSUBSTNO has been called:\%1
CopyCode image Copy Code
Str := Text000;
AccountNo := 3452;
Balance := 2345 + 5462;
MESSAGE(Text001, Str);
Str := STRSUBSTNO(Str, AccountNo, Balance);
MESSAGE(Text002, Str);

The first message window displays the following text:

The string before STRSUBSTNO has been called:

The balance of account %1 is $ %2

The second message window displays the following text:

The string after STRSUBSTNO has been called:

The balance of account 3452 is $ 7,807

Note Note

This example is run on a computer with the regional format set to English (United States).

Expand image See Also

Reference

Code Data Type
Text Data Type


UPPERCASE Function (Code, Text)

UPPERCASE Function (Code, Text)
See Also Example
CollapseAll image

Converts all letters in a string to uppercase.

NewString := UPPERCASE(String)

Parameters

String

Type: Text constant or code

The string that you want to convert to uppercase.

Expand image Property Value/Return Value

Type: Text constant or code

The resulting string after it has been converted to uppercase.

Expand image Example

The following example shows how to use the UPPERCASE function.

This example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text000 | 'Outstanding Order Status'
Text001 | 'The test string before UPPERCASE is called:\%1'
Text002 | 'The string after UPPERCASE is called:\%1'
CopyCode image Copy Code
Lower := Text000;
MESSAGE(Text001, Lower);
Upper := UPPERCASE(Lower);
MESSAGE(Text002, Upper);

The first message window displays the following:

The test-string before UPPERCASE is called:

Outstanding Order Status

The second message window displays the following:

The string after UPPERCASE is called:

OUTSTANDING ORDER STATUS

Expand image See Also

Reference

Code Data Type
Text Data Type


System

System

This section contains the following topics:

  • Array Functions

  • CodeCoverage Functions

  • Language Functions

  • Operating System Functions

  • Variable Functions


Array Functions

Array Functions

This section contains the following topics:

  • ARRAYLEN Function

  • COMPRESSARRAY Function

  • COPYARRAY Function


ARRAYLEN Function

ARRAYLEN Function
See Also Example
CollapseAll image

Returns the total number of elements in an array or the number of elements in a specific dimension.

Length := ARRAYLEN(Array[, Dimension])

Parameters

Array

Type: Any

The array that you want to investigate.

Dimension

Type: Integer

If you omit this optional argument, the function returns the total number of elements in the array. To get the number of elements in a specific dimension, use Dimension with a valid value. The valid values are determined by the number of dimensions of the input array. For example, the valid values for a three-dimensional array would be 1, 2, and 3.

Expand image Property Value/Return Value

Type: Integer

The number of elements in the array, or the number of elements in a specific dimension.

Expand image Remarks

If you use ARRAYLEN with an input parameter that is not an array, a run-time error occurs.

Expand image Example

This example shows how to use the ARRAYLEN function.

This example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text000 | 'Array1, Total number of elements %1'
Text001 | 'Array2, Dimension no 1: Size %1'
Text002 | 'Array2, Dimension no 2: Size %1'
Text003 | 'Array2, Total number of elements: %1'
CopyCode image Copy Code
// Array1 is a one-dimensional integer array with size 2
// Array2 is a two-dimensional integer array with size 2x2
MESSAGE(Text000, ARRAYLEN(Array1));
MESSAGE(Text001, ARRAYLEN(Array2,1));
MESSAGE(Text002, ARRAYLEN(Array2,2));
MESSAGE(Text003, ARRAYLEN(Array2));

The following messages are displayed.

Array1, Total number of elements: 2

Array2, Dimension no. 1: Size 2

Array2, Dimension no. 2: Size 2

Array2, Total number of elements: 4

Expand image See Also

Reference

COMPRESSARRAY Function
COPYARRAY Function


COMPRESSARRAY Function

COMPRESSARRAY Function
See Also Example
CollapseAll image

Moves all non-empty strings (text) in an array to the beginning of the array. The resulting StringArray has the same number of elements as the input array, but empty entries and entries that contain only blanks appear at the end of the array.

[Count =:] COMPRESSARRAY(StringArray)

Parameters

StringArray

Type: Array of strings

The string array that you want to compress.

Expand image Property Value/Return Value

Type: Integer

The number of non-empty strings that were compressed.

Expand image Remarks

When compressing an array of strings, the non-empty strings in the resulting array are sorted in the same way as in the original array.

The COMPRESSARRAY function is especially useful for printing names and addresses. For instance, you can use this function to remove blank lines in account statements.

This function compresses an array of Text or Code (not BigText). The compression is done by moving empty strings to the end of the array.

For example, "Redmond", "Copenhagen", "", "Fargo", "Paris" is changed to "Redmond", "Copenhagen", "Fargo", "Paris", "".

In Microsoft Dynamics NAV 2009, it is not supported to use the CompressArray function on multidimensional arrays. In previous versions, CompressArray works for arrays of arrays.

Expand image Example

This example shows how to use the COMPRESSARRAY function. The input StringArray has the following values:

Joe Raybon

One Meca Way

Atlanta

The output StringArray has the following values:

Joe Raybon

One Meca Way

Atlanta

All non-empty entries have been moved to the beginning of the array.

This example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text000 | 'Joe Raybon'
Text001 | 'One Meca Way'
Text002 | 'Atlanta'
Text003 | 'Before compression, the address is…\%1\%2\%3\%4\%5\%6'
Text004 | 'After compression, the address is…\%1\%2\%3\%4\%5\%6'
CopyCode image Copy Code
Name[1] := ''; // Empty String
Name[2] := Text000;
Name[3] := Text001;
Name[4] := ' '; // A string containing blanks
Name[5] := Text002;
Name[6] := '';
MESSAGE(Text003, Name[1], Name[2], Name[3], Name[4], Name[5], Name[6]);
COMPRESSARRAY(Name); // The empty lines (strings) are removed
MESSAGE(Text004, Name[1], Name[2], Name[3],Name[4], Name[5], Name[6]);

The first message window displays the following:

Before compression, the address is...

Joe Raybon

One Meca Way

Atlanta

The second message window displays the following:

Joe Raybon

One Meca Way

Atlanta

All empty and blank strings, which cause blank lines, are moved to the end of the array. The other elements are moved to the beginning of the array.

Note Note

Empty lines are not printed if they occur on the first or last line in a message window.

Expand image See Also

Reference

ARRAYLEN Function
COPYARRAY Function


COPYARRAY Function

COPYARRAY Function
See Also Example
CollapseAll image

Copies one or more elements in an array to a new array.

COPYARRAY(NewArray, Array, Position[, Length])

Parameters

NewArray

Type: Array

The array to copy to; the destination array.

Array

Type: Array

The array to copy from; the source array.

Position

Type: Integer

The position of the first array element to copy.

Length

Type: Integer

The number of array elements to copy. If you do not specify Length, all array elements are copied from Position to the last element. Use this equation to determine valid values:

1 =< LENGTH =< MAXLEN(ARRAY) - POSITION + 1

Expand image Remarks

You can only copy from one-dimensional arrays. Repeat the COPYARRAY function to copy two- and three-dimensional arrays.

Expand image Example

If array1 is an integer array with dimension 10, and it contains the numbers from 1 to 10, the following command copies the numbers 6,7,8,9,10 to array2, an integer array with dimension 5.
CopyCode image Copy Code
COPYARRAY (array2,array1,6,5);

If array1 is an integer array with dimension 10, and it contains the numbers from 1 to 10, the following command copies the numbers 6,7,8,9,10 to array2, an integer array with dimension 5. In this example the length parameter has been omitted.
CopyCode image Copy Code
COPYARRAY (array2,array1,6);

The effect would be exactly the same as the first example because in this example, the default copying of everything from position 6 and forward from array1 just happens to fit in array2, which has a dimension of 5.

If array1 is an integer array with dimension 10, and it contains the numbers from 1 to 10, and array2 is an integer array with dimension 5, the following command causes a run-time error.
CopyCode image Copy Code
COPYARRAY (array2,array1,3);

This example causes a run-time error because seven elements would be copied from array1 to array2 and array2 has only room for five.

Expand image See Also

Reference

ARRAYLEN Function
COMPRESSARRAY Function


CodeCoverage Functions

CodeCoverage Functions

This section contains the following topic:

  • CODECOVERAGELOG Function


CODECOVERAGELOG Function

CODECOVERAGELOG Function

Starts and stops the logging of code. You can also use this function to retrieve the current logging status.

[IsActive :=] CODECOVERAGELOG([NewIsActive])

Parameters

NewIsActive

Type: Boolean

Expand image Property Value/Return Value

Type: Boolean

Expand image Remarks

This function is not supported in the RoleTailored client.

You must only start the Code Coverage tool from the command prompt when you want to get a total overview of the code used when running Microsoft Dynamics NAV or when you are testing the application.

To start Microsoft Dynamics NAV with the Code Coverage tool on, enter the following command:

fin COVERAGELOG

To start Microsoft Dynamics NAV with the Code Coverage tool on and to log the results in file xx.xx, enter the following command:

fin COVERAGELOG, COVERAGEFILENAME=xx.xx

To start Microsoft Dynamics NAV with the Code Coverage tool set to off and to load an existing result from file xx.xx, enter the following command:

fin COVERAGEFILENAME=xx.xx.

Running the Code Coverage tool for this purpose will generate a very large log file.

Expand image See Also

Concepts

Code Coverage Tool


Language Functions

Language Functions

This section contains the following topics:

  • GLOBALLANGUAGE Function

  • LANGUAGE Function

  • WINDOWSLANGUAGE Function


GLOBALLANGUAGE Function

GLOBALLANGUAGE Function

Sets and retrieves the current C/SIDE global language setting.

[LanguageID :=] GLOBALLANGUAGE([NewLanguageID])

Parameters

NewLanguageID

Type: Integer

Expand image Property Value/Return Value

Type: Integer

Expand image Remarks

The LanguageID is a standard Windows language ID. The Windows Language virtual table contains a list of these IDs and the corresponding names and short names.

For more information, see Working with Multilanguage Functionality.

Expand image See Also

Reference

LANGUAGE Function
WINDOWSLANGUAGE Function


LANGUAGE Function

LANGUAGE Function

Sets and retrieves the current language setting for an object (form, report, or dataport).

[CurrLanguage :=] LANGUAGE([NewLanguage])

Parameters

NewLanguage

Type: Integer

Expand image Property Value/Return Value

Type: Integer

Expand image Remarks

CurrLanguage and NewLanguage are standard Windows language IDs. The Windows Language virtual table contains a list of these IDs and the corresponding names and short names.

You cannot set or retrieve the language for objects other than forms, reports, and dataports.

This function is not supported in the RoleTailored client.

For more information, see Working with Multilanguage Functionality.

Expand image See Also

Reference

GLOBALLANGUAGE Function
WINDOWSLANGUAGE Function


WINDOWSLANGUAGE Function

WINDOWSLANGUAGE Function

Retrieves the current Windows language setting.

LanguageID := WINDOWSLANGUAGE

Expand image Property Value/Return Value

Type: Integer

Expand image Remarks

The LanguageID is a standard Windows language ID. The Windows Language virtual table contains a list of these IDs and the corresponding names and short names.

For more information, see Working with Multilanguage Functionality.

Expand image See Also

Reference

GLOBALLANGUAGE Function
LANGUAGE Function


Operating System Functions

Operating System Functions

This section contains the following topics:

  • APPLICATIONPATH Function

  • COMMANDLINE Function

  • CONTEXTURL Function

  • ENVIRON Function

  • GUIALLOWED Function

  • HYPERLINK Function

  • OSVERSION Function

  • SHELL Function

  • SLEEP Function

  • TEMPORARYPATH Function


APPLICATIONPATH Function

APPLICATIONPATH Function

Returns the path to the directory where the executable file for Microsoft Dynamics NAV is installed.

APPLICATIONPATH

Expand image Remarks

This function returns a string that contains the path to the directory where the executable file for Microsoft Dynamics NAV is installed. This string ends with a backslash ('\') and does not contain the name of the executable file.

The string cannot contain more than 255 characters.

If this function is called from an application that is running on a Microsoft Dynamics NAV Application Server, it returns the path to the directory where the Microsoft Dynamics NAV Application Server is installed.

Expand image See Also

Reference

COMMANDLINE Function
CONTEXTURL Function
ENVIRON Function
GUIALLOWED Function
HYPERLINK Function
OSVERSION Function
SHELL Function
SLEEP Function
TEMPORARYPATH Function


COMMANDLINE Function

COMMANDLINE Function
See Also Example
CollapseAll image

Returns a list of the parameters used to start Microsoft Dynamics NAV.

String := COMMANDLINE

Expand image Property Value/Return Value

Type: Text or code

Contains a list of the parameters used to start Microsoft Dynamics NAV.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image Example

If you started Microsoft Dynamics NAV with the following command:

c:\Program Files\Microsoft Dynamics NAV\Fin database=xyzco

Then run the COMMANDLINE function, the return string will be the following:

database=xyzco

CopyCode image Copy Code
ReturnString := COMMANDLINE

Expand image See Also

Reference

APPLICATIONPATH Function
CONTEXTURL Function
ENVIRON Function
GUIALLOWED Function
HYPERLINK Function
OSVERSION Function
SHELL Function
SLEEP Function
TEMPORARYPATH Function


CONTEXTURL Function

CONTEXTURL Function
See Also Example
CollapseAll image

Returns a context string that defines the current position of the running objects.

String := CONTEXTURL

Expand image Property Value/Return Value

Type: Text or code

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image Example

The following examples show context strings that could be the return value of the CONTEXTURL function.
CopyCode image Copy Code
navision://client/run?database=filename&company=companyname
navision://client/run?server=servername&company=companyname&servertype=MSSQL

Expand image See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
ENVIRON Function
GUIALLOWED Function
HYPERLINK Function
OSVERSION Function
SHELL Function
SLEEP Function
TEMPORARYPATH Function


ENVIRON Function

ENVIRON Function

Returns a string associated with an environment variable.

String := ENVIRON(Name)

Parameters

Name

Type: Text constant or code

The name of the environment variable.

Expand image Property Value/Return Value

Type: Text constant or code

The string associated with the environment variable.

Expand image Remarks

If the environment variable does not exist, the string that is returned may contain erroneous information.

This function is not supported in the RoleTailored client.

Expand image See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
CONTEXTURL Function
GUIALLOWED Function
HYPERLINK Function
OSVERSION Function
SHELL Function
SLEEP Function
TEMPORARYPATH Function


GUIALLOWED Function

GUIALLOWED Function
See Also Example
CollapseAll image

Checks whether the C/AL code is allowed to show any information on the screen.

[Ok :=] GUIALLOWED

Expand image Property Value/Return Value

Type: Boolean

If the return value is true, then the C/AL code is running on a C/SIDE client and the GUI is available.

If the return value is false, then the C/AL code is running on Microsoft Dynamics NAV Application Server and no GUI is available.

Expand image Remarks

User Portal Application Server accepts GUIALLOWED.

Expand image Example

This example shows how to use the GUIALLOWED function.

This example requires that you create the following text constant in the C/AL Globals window.

Text constant | ENU value
Text000 | Code is running on a C/SIDE client.
CopyCode image Copy Code
IF GUIALLOWED THEN
 MESSAGE(Text000);

If the code runs on a C/SIDE client, which means that the user interface is available, a message box will appear with the following message.

Code is running on a C/SIDE client

If the code runs on Microsoft Dynamics NAV Application Server, the message will not be displayed.

Note Note

If the MESSAGE Function (Dialog) or the ERROR Function (Dialog) is called when the code is running on Microsoft Dynamics NAV Application Server, the message is written to the event log of the operating system. For more information about message logging, see the manual Installation & System Management: Microsoft Dynamics NAV Application Server.

Expand image See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
CONTEXTURL Function
ENVIRON Function
HYPERLINK Function
OSVERSION Function
SHELL Function
SLEEP Function
TEMPORARYPATH Function


HYPERLINK Function

HYPERLINK Function
See Also Example
CollapseAll image

Passes a URL as an argument to an Internet browser, such as Microsoft Internet Explorer.

HYPERLINK(URL)

Parameters

URL

Type: Text

A URL that is passed to the default Internet browser as an argument.

Expand image Remarks

C/SIDE does not check the syntax or validity of the URL that is passed on to the browser. You can even pass an empty string (this will usually start the browser and load the URL that the user has defined as the home page.)

C/SIDE determines the default Internet browser based on the setting in the system registry. If the browser is already running, this instance will be reused.

The HYPERLINK function works with a number of protocols and file types. These protocols and file types are listed in the .stx file. This means that different versions of Microsoft Dynamics NAV can use different protocols and file types.

The following list shows the approved protocols and file types for the Microsoft Dynamics NAV 2009 standard version:

  • Protocols

    • Navision (opens the Classic client)

    • DynamicsNAV (opens the RoleTailored client)

    • http

    • https

  • File Types

    • bmp

    • doc

    • docx

    • dot

    • htm

    • html

    • mhtml

    • mht

    • fig

    • gif

    • ini

    • jpg

    • mdb

    • mov

    • mpeg

    • mpg

    • pub

    • pdf

    • ppt

    • pps

    • rtf

    • sys

    • txt

    • url

    • wri

    • wpd

    • wps

    • xls

    • xlsx

    • xsn

    • xml

    • zip

    • fdf

    • aspx

    • chm

    • vsd

    • mpp

    • wmv

    • wma

    • msg

    • tif

    • png

The HYPERLINK function does not work on Microsoft Dynamics NAV Application Server.

Expand image Example

To create a command button that starts the default Internet browser and directs it to the Microsoft site on the World Wide Web, you could add the code in the following example to the OnPush Trigger of the command button.
CopyCode image Copy Code
HYPERLINK('http://www.microsoft.com');

Expand image See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
CONTEXTURL Function
ENVIRON Function
GUIALLOWED Function
OSVERSION Function
SHELL Function
SLEEP Function
TEMPORARYPATH Function


OSVERSION Function

OSVERSION Function
See Also Example
CollapseAll image

Returns a string which contains the name and version of the operating system or operating environment.

String := OSVERSION

Expand image Property Value/Return Value

Type: Text constant or code

Specifies the type and version of the operating system or operating environment. The following table shows examples.

Operating system | Return value
Windows XP | Windows_NT_5.1
Windows Server 2003 | Windows_NT_5.2
Windows Vista | Windows_NT_6.0.1
Windows Server 2008 (domain controller) | Windows_NT_6.0.2
Windows Server 2008 | Windows_NT_6.0.3

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image Example

This example shows how to use the OSVERSION function.

This example requires that you create the following text constant in the C/AL Globals window.

Text constant | ENU value
Text000 | 'The operating system is: %1'
CopyCode image Copy Code
Ver := OSVERSION;
MESSAGE(Text000, Ver);

The following is a typical result:

The operating system is: Windows_NT_6.0.1

Expand image See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
CONTEXTURL Function
ENVIRON Function
GUIALLOWED Function
HYPERLINK Function
SHELL Function
SLEEP Function
TEMPORARYPATH Function


SHELL Function

SHELL Function
See Also Example
CollapseAll image

Executes external programs and operating system commands from C/AL programs.

[ReturnCode :=] SHELL(Name[, Param, ...])

Parameters

Name

Type: Text or code

The path and name of the command. The following rules apply:

  • You can omit the drive designation if the command is located on the current drive.

  • You can omit the full path if the command is located in the current directory.

  • You can enter only the subdirectory name if the command is located in a subdirectory of the current directory.

Param

Type: Text or code

One or more optional parameters sent with the external program or command.

The parameters cannot be passed as part of the Name parameter. The Name parameter must be filled in and it must not contain any parameters except for the executable. The parameter information must be hard-coded as a text constant or as a variable.

The SHELL function has been designed so that each user can create a list of trusted executables. This list is maintained in the user’s .zup file. The way this function works depends on whether the executable is given as a text constant or as a variable.

If the name of the executable is passed to the SHELL function as a text constant then the executable is trusted and the user is not prompted to confirm that they trust the executable. This is also the case when the executable (text constant) is called with a number of other arguments that have been assigned manually.

If the name of the executable is passed to the SHELL function as a variable then the executable is not trusted and the user is prompted to confirm whether they trust the executable the first time it is called. After the user has confirmed that they trust the executable it can be called again at any time without having to confirm that it is trusted.

Expand image Property Value/Return Value

Type: Integer

The return value is used for the following purposes:

  • If the return value is used, then the external program will be run modally; otherwise, it will be run non-modally. For example, if you want to go to the operating system and get a directory listing and then bring that information back, include the return value. Omit the return value if you want to run the external program non-modally. For example, if all you want to do is pass information (such as a name and address) to a standardized letter that is set up in a word processor, you would omit the return value.

  • The return value can contain the return value of the external program. Since external programs can return different codes to reflect whether errors occurred during the execution of the program, the values stored in ReturnCode depend on the external program.

Expand image Remarks

You can run this function modally or non-modally, depending on whether you include the return value from the external program in your code.

The SHELL function can only be used with a text constant on Microsoft Dynamics NAV Application Server.

The SHELL function is not supported in the RoleTailored client.

Expand image Example

CopyCode image Copy Code
OBJECT Codeunit 98123 SHELL ex
{
  OBJECT-PROPERTIES
  {
    Date=30-08-04;
    Time=14:12:57;
    Modified=Yes;
    Version List=;
  }
  PROPERTIES
  {
    OnRun=BEGIN
            // The following is not trusted and will give a warning.
            ExecName := 'C:\windows\notepad.exe';
            param := 'C:\MyFile.txt';
            ret := SHELL(ExecName, param);
            // The following is trusted and will not give a warning.
            param := 'C:\MyFile.txt';
            ret := SHELL(TEXT000, param);
            // The following is not possible - will only give an error
            // message during runtime. This is also if its a TextConst:
            ExecName := 'C:\windows\notepad.exe C:\MyFile.txt';
            ret := SHELL(ExecName);
          END;
  }
  CODE
  {
    VAR
      ret@1000 : Integer;
      param@1001 : Text[30];
      TEXT000@1002 : TextConst 'ENU=C:\windows\notepad.exe';
      ExecName@1003 : Text[30];
    BEGIN
    END.
  }
}

Expand image See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
CONTEXTURL Function
ENVIRON Function
GUIALLOWED Function
HYPERLINK Function
OSVERSION Function
SLEEP Function
TEMPORARYPATH Function


SLEEP Function

SLEEP Function

Returns control to the operating system for a specifiable amount of time.

SLEEP(Duration)

Parameters

Duration

Type: Integer

The number of milliseconds to return control to the operating system.

Expand image Remarks

When using SLEEP, control is guaranteed to return to the operating system for at least Duration milliseconds (implying that the period may be longer, depending on what the operating system is doing at the time when control is to return to the caller.)

Expand image See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
CONTEXTURL Function
ENVIRON Function
GUIALLOWED Function
HYPERLINK Function
OSVERSION Function
SHELL Function
TEMPORARYPATH Function


TEMPORARYPATH Function

TEMPORARYPATH Function

Returns the path to the directory where the temporary file for Microsoft Dynamics NAV is stored.

TEMPORARYPATH

Expand image Remarks

This function returns a string that contains the path to the directory where the temporary file for Microsoft Dynamics NAV is stored. This string ends with a backslash ('\') and does not contain the name of the temp file.

The string cannot contain more than 255 characters.

If this function is called from an application that is running on a Microsoft Dynamics NAV Application Server, it returns the path to the directory where the Microsoft Dynamics NAV Application Server is installed.

Expand image See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
CONTEXTURL Function
ENVIRON Function
GUIALLOWED Function
HYPERLINK Function
OSVERSION Function
SHELL Function
SLEEP Function


Variable Functions

Variable Functions

This section contains the following topics:

  • CLEAR Function

  • CLEARALL Function

  • EVALUATE Function

  • VARIABLEACTIVE Function


CLEAR Function

CLEAR Function
See Also Example
CollapseAll image

Clears the value of a single variable. Also clears all the filters that were set if the variable is a record and resets the key to the primary key.

CLEAR(Variable)

Parameters

Variable

Type: Any

The identifier (variable) of any C/AL data type, including simple and composite data types. The following rules apply when you run the CLEAR function:

  • A number variable is set to 0 (zero)

  • A string variable is set to empty string

  • A date variable is set to 0D (undefined date)

  • A time variable is set to 0T (undefined time)

  • A Boolean variable is set to FALSE

Expand image Remarks

Use the CLEARALL Function to clear all internal variables, keys, and filters in the object and in any associated objects such as reports, forms, and codeunits that contain C/AL code. Note, however, that CLEARALL does not affect or change values for variables in single instance codeunits.

For a composite data type, such as a record or an array, all elements are cleared. Furthermore, all fields in a record will be initialized with the InitValue Property of the field.

CLEAR can also be used on the GUID Data Type. It converts the GUID to zeros. Use the CREATEGUID function to create a new unique GUID.

For an Automation object, CLEAR releases the Automation object and decreases the reference count. The Automation server determines if this should cause a shutdown. After CLEAR, you can use the CREATE Function (Automation) on the Automation variable to create a new instance of the object.

If you use CLEAR on a codeunit, only the reference to the codeunit is deleted and not the codeunit itself, as with Automation objects. This means that the content of the codeunit stays intact.

If you have an array of controls, the whole array is destroyed when the array variable goes out of scope.

If you have an array of automation servers, you may CLEAR the whole array at once, or CLEAR each element individually.

Expand image Example

This example shows how to use the CLEAR function.

This example requires that you create the following text constants in the C/AL Globals window

Text constant | ENU value
Text000 | 'Joe Raybon'
Text001 | 'Initially the variable "Name" contains: >%1<'
Text002 | 'After using CLEAR, the variable "Name" contains: >%1<'
CopyCode image Copy Code
Name := Text000;
MESSAGE(Text001, Name);
CLEAR(Name);
MESSAGE(Text002, Name);

The first message window displays the following:

Initially the variable "Name" contains: >Joe Raybon<

The second message window displays the following:

After using CLEAR, the variable "Name" contains: ><

In the following example you will declare two variables:

CopyCode image Copy Code
MyTextVar, data type: "text".
GuidVar, data type: "GUID".

These variables will be declared and cleared, first by using CLEAR and then by using CLEARALL.

This example requires that you create the following text constants in the C/AL Globals window

Text constant | ENU value
Text000 | My Text
Text001 | Initially the variable "MyTextVar" contains >%1< and "GuidVar" is defined as >%2<
Text002 | After using CLEAR(MyTextVar), the variable "MyTextVar" contains >%1< and "GuidVar" is still defined as >%2<
Text003 | After using CLEAR(GuidVar) the variable "GuidVar" becomes undefined
Text004 | Giving the "MyTextVar" variable the initial value again and creating a new "GuidVar" results in >%1< and >%2<
Text005 | Using CLEARALL results in an empty "MyTextVar" >%1< and an undefined "GuidVar"
CopyCode image Copy Code
MyTextVar := Text000;
GuidVar := CREATEGUID();
MESSAGE(Text001,MyTextVar,GuidVar);
CLEAR(MyTextVar);
MESSAGE(Text002,MyTextVar,GuidVar);
CLEAR(GuidVar);
MESSAGE(Text003,GuidVar);
MyTextVar := Text000;
GuidVar := CREATEGUID();
MESSAGE(Text004,MyTextVar,GuidVar);
CLEARALL;
MESSAGE(Text005,MyTextVar,GuidVar);

The first message window displays the following:

Initially the variable "MyTextVar" contains: >My Text< and "GuidVar" is defined as >12345678-1234-1234-1234-1234567890AB<

The second message window displays the following:

After using CLEAR(MyTextVar), the variable "MyTextVar" contains: >< and GuidVar is still defined as >12345678-1234-1234-1234-1234567890AB<

The third message window displays the following:

After using CLEAR(GuidVar) the variable "GuidVar" becomes undefined

The fourth message window displays the following:

Giving the "MyTextVar" variable the initial value again and creating a new "GuidVar" results in >My Text< and >87654321-4321-4321-4321-BA0987654321<

The fifth message window displays the following:

Using CLEARALL results in an empty "MyTextVar" >< and an undefined "GuidVar"

Expand image See Also

Reference

CLEARALL Function
COPYSTREAM Function (InStream, OutStream)
EVALUATE Function


CLEARALL Function

CLEARALL Function

Clears all internal variables (except REC variables), keys, and filters in the object and in any associated objects, such as reports, forms, codeunits, and so on that contain C/AL code.

CLEARALL

Expand image Remarks

CLEARALL works by calling the CLEAR Function repeatedly on each variable. However, this is not the case with codeunits, where the CLEARALL function works by calling CLEARALL inside the codeunit. It deletes the contents of the codeunit, whereas CLEAR only deletes the reference to the codeunit.

CLEARALL does not affect or change values for variables in single instance codeunits.

When a function is called repeatedly within the same transaction, the system retains all values for variables and filters in memory between calls. For example, this is used to assign numbers to entry numbers when posting. When you do not want to retain the values in memory, use the CLEARALL function to clear them.

For information about the initial values of cleared variables, see the CLEAR Function. Take into consideration that fields in a record will be initialized with the InitValue Property of the field.

Expand image See Also

Reference

CLEAR Function
COPYSTREAM Function (InStream, OutStream)
EVALUATE Function


EVALUATE Function

EVALUATE Function
See Also Example
CollapseAll image

Evaluates a string representation of a value into its normal representation. The result is assigned to a variable.

[Ok :=] EVALUATE(Variable, String[, Number])

Parameters

Variable

Type: Boolean, integer, option, date, time, text constant, code, or GUID

Any type of variable. The value of the string is assigned to the variable

String

Type: Text constant or code

A string containing a value of any simple C/AL data type

Number

Type: Integer

This optional value can be used when exporting data with an XMLport. The only valid value is 9, which indicates that the data must be converted from XML format to C/SIDE format.

Expand image Property Value/Return Value

Type: Boolean

Specifies whether an error occurred during the evaluation of the string.

If the return value is true, then no errors occurred during the evaluation of the string and the value was assigned to Variable.

If the return value is false, then errors occurred during the evaluation of the string and the original value of Variable was not modified.

Expand image Example

This example shows how to use the EVALUATE function when called with three different types of variables.

This example requires that you create the following text constants in the C/AL Globals window.

Text constant | ENU value
Text000 | 'VarInteger = #1######, and the return code is: %2\'
Text001 | 'VarDate = #3######, and the return code is: %4\'
Text002 | 'VarYesNo = #5######, and the return code is: %6'
CopyCode image Copy Code
Value := '010196';
Ok1 := EVALUATE(VarInteger, Value);
Ok2 := EVALUATE(VarDate, Value);
Ok3 := EVALUATE(VarYesNo, Value);
MESSAGE(Text000 + Text001 + Text002, VarInteger, Ok1, VarDate, Ok2, VarYesNo, Ok3)

The message window displays the following:

VarInteger = 10196 , and the return code is: Yes

VarDate = 01/01/96, and the return code is: Yes

VarYesNo = No , and the return code is: No

This example shows that while Value ('010196') can be interpreted as both an integer and a date expression, it cannot be interpreted as a Boolean expression. This causes an error, shown in the return code Ok3 (=FALSE).

Expand image See Also

Reference

CLEAR Function
CLEARALL Function
COPYSTREAM Function (InStream, OutStream)


VARIABLEACTIVE Function

VARIABLEACTIVE Function

Determines if a variable, such as field or a control, is active or inactive.

IsActive := VARIABLEACTIVE(Variable)

Parameters

Variable

The variable that you want to investigate.

Expand image Property Value/Return Value

Type: Boolean

true if the variable is active; otherwise false.

Expand image Remarks

This function is not supported in the RoleTailored client.

Expand image See Also

Concepts

Variable Functions


TableFilter Data Type

TableFilter Data Type

Applies a filter to another table. Currently, this data type can only be used when you are setting security filters from the Permission table.


Variant Data Type

Variant Data Type

The C/AL variant data type can contain any variants from OCX and Automation objects (VT_VARIANT). However, not all these values can be mapped to C/AL values. For more information, see Using COM Technologies in C/SIDE.

The variant data type can contain the following C/AL data types:

  • Record

  • File

  • Action

  • Codeunit

  • Automation

  • Boolean

  • Option

  • Integer

  • Decimal

  • Char

  • Text

  • Code

  • Date

  • Time

  • Binary

  • DateFormula

  • TransactionType

  • InStream

  • OutStream

You can use the variant data type to pass Automation variants from one external component (Automation or OCX) to another. This requires that the recipient component can accept the original variant. You can also assign a C/AL variable to a variant and pass it to an external component. When you pass C/AL variants ByRef to an external COM component, small conversion differences may occur. Therefore, we recommend that you pass C/AL variants ByVal if you do not need to assign a new value to the C/AL variant in your external component.

Expand image Returning Variants in Internal Function Calls

The C/AL variant is a complex data type. To return C/AL variants in function calls, you must pass them in a parameter ByVar (called ByRef in COM).

Expand image Returning DateTime Variants

In the Classic client, if an Automation method returns a DateTime in a variant, then the time component is removed when the variant variable is converted to a typed variable. If an Automation method returns a value in a method argument, then the time component is not removed. For example, the following code calls an Automation method that returns a variant and returns a value in one of the arguments of the method. This example requires that you create the following variables.

Variable | Data type
varAutomation | Automation
varVariant | Variant
returnVariant | Variant
outVariant | Variant
varDate | Date
varTime | Time
varDateReturn | Date
varDateOut | Date
CopyCode image Copy Code
// Create a variant that contains date and time.
varVariant := DATI2VARIANT(varDate, varTime);
// Call an automation method that takes two VT_DATE arguments:
// varVariant and outVariant.
// The method returns a value in the outVariant argument.
returnVariant := varAutomation.MethodDateData(varVariant, outVariant);
varDateReturn := returnVariant;
varDateOut := VARIANT2DATE(outVariant);

In this example, you must convert the returnVariant and the outVariant variables to Date variables in different ways. You can assign returnVariant, which is the variant that the method returns, directly to a Date variable because the time component is removed automatically. You must call VARIANT2DATE on outVariant, which is the method argument, because the time component is not removed.

In the RoleTailored client, the time component is not removed from either a variant return value or a variant method argument when the variant variable is converted to a typed variable.

Expand image Variants and Approximation

A C/AL variant contains two allocation areas: one for C/AL variables and one for Automation and OCX variants. This means that every time you assign a C/AL variable to a variant, the variant will contain the same data as the original variable. The conversion process does not change the data in any way. However, this is not the case with DATI2VARIANT because it is a VT_VARIANT. When you assign an external variable to a variant, the variant will also contain the same data as the original external variable.

Expand image Assigning Automation Variants to FieldRef Values

In Microsoft Dynamics NAV 2009, if an automation method returns a byte string (bstr) in a variant, you cannot assign that variant directly to a field that is a Code data type. Instead, you must first assign the variant to a code variable, and then assign the code variable to the FieldRef value. For example, the following code assigns a variant from an automation method to a variable, and then assigns the variable to a field.

CopyCode image Copy Code
CodeVariable := AutomationMetodReturningBStrInVariant();
FieldRef.Value := CodeVariable;

In previous versions of C/SIDE, you could assign the variant directly to a Code FieldRef value.

Expand image See Also

Reference

DATI2VARIANT Function (Date, Variant)
ISACTION Function (Variant)
ISAUTOMATION Function (Variant)
ISBINARY Function (Variant)
ISBOOLEAN Function (Variant)
ISCHAR Function (Variant)
ISCODE Function (Variant)
ISCODEUNIT Function (Variant)
ISDATE Function (Variant)
ISDATEFORMULA Function (Variant)
ISDECIMAL Function (Variant)
ISFILE Function (Variant)
ISINSTREAM Function (Variant)
ISINTEGER Function (Variant)
ISOPTION Function (Variant)
ISOUTSTREAM Function (Variant)
ISRECORD Function (Variant)
ISTEXT Function (Variant)
ISTIME Function (Variant)
ISTRANSACTIONTYPE Function (Variant)
VARIANT2DATE Function (Date, Variant)
VARIANT2TIME Function (Date, Variant)


ISACTION Function (Variant)

ISACTION Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains an action variable.

Ok := Variant.ISACTION

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains an action variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISAUTOMATION Function (Variant)

ISAUTOMATION Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains an automation variable.

Ok := Variant.ISAUTOMATION

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains an automation variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISBINARY Function (Variant)

ISBINARY Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a binary variable.

Ok := Variant.ISBINARY

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a binary variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISBOOLEAN Function (Variant)

ISBOOLEAN Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a Boolean variable.

Ok := Variant.ISBOOLEAN

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a Boolean variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISCHAR Function (Variant)

ISCHAR Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a char variable.

Ok := Variant.ISCHAR

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a char variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISCODE Function (Variant)

ISCODE Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a code variable.

Ok := Variant.ISCODE

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a code variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISCODEUNIT Function (Variant)

ISCODEUNIT Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a codeunit variable.

Ok := Variant.ISCODEUNIT

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a codeunit variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISDATE Function (Variant)

ISDATE Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a date variable.

Ok := Variant.ISDATE

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a date variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISDATEFORMULA Function (Variant)

ISDATEFORMULA Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a dateformula variable.

Ok := Variant.ISDATEFORMULA

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a dateformula variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISDECIMAL Function (Variant)

ISDECIMAL Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a decimal variable.

Ok := Variant.ISDECIMAL

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a decimal variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISFILE Function (Variant)

ISFILE Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a file variable.

Ok := Variant.ISFILE

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a file variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISINSTREAM Function (Variant)

ISINSTREAM Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains an InStream variable.

Ok := Variant.ISINSTREAM

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains an InStream variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISINTEGER Function (Variant)

ISINTEGER Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains an integer.

Ok := Variant.ISINTEGER

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains an integer; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISOPTION Function (Variant)

ISOPTION Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains an option variable.

Ok := Variant.ISOPTION

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains an option variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISOUTSTREAM Function (Variant)

ISOUTSTREAM Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains an OutStream variable.

Ok := Variant.ISOUTSTREAM

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains an OutStream variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISRECORD Function (Variant)

ISRECORD Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a record variable.

Ok := Variant.ISRECORD

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a record variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISTEXT Function (Variant)

ISTEXT Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a text variable.

Ok := Variant.ISTEXT

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a text variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISTIME Function (Variant)

ISTIME Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a time variable.

Ok := Variant.ISTIME

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a time variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


ISTRANSACTIONTYPE Function (Variant)

ISTRANSACTIONTYPE Function (Variant)
See Also
CollapseAll image

Indicates whether a C/AL variant contains a transactiontype variable.

Ok := Variant.ISTRANSACTIONTYPE

Parameters

Variant

Type: Variant

Expand image Property Value/Return Value

Type: Boolean

true if the C/AL variant contains a transactiontype variable; otherwise, false.

Expand image See Also

Reference

Variant Data Type


XMLport Data Type

XMLport Data Type

The XMLport object is conceptually related to a dataport. You can also use XMLports to import and export data, but in XML format. XMLports make the process of exchanging data in XML between systems more simple and streamlined. You only need a basic knowledge of XML and you do not have to create XML documents using external products.

If you have used dataports to import or export data, your application will run on the Classic client but will result in run-time errors on the RoleTailored client. If your application runs on both the Classic and the RoleTailored clients, we recommend that you use XMLports instead of dataports to import and export data. XMLports are supported on both the Classic and RoleTailored clients. You can configure XMLport objects to achieve the same functionality as dataports in previous versions of Microsoft Dynamics NAV.

When you are developing for Microsoft Dynamics NAV Server, you can use additional properties and have access to additional functionality. Request pages and import and export text functionality have been added to XMLports. These properties are visible in the Classic client so that you can access them in XMLport Designer. However, setting or executing an XMLport with these properties in the Classic client has no effect.

Importing and exporting text also works differently in XMLports:

  • XMLports do not have an OnBeforeExportRecord trigger.

  • XMLports support multiple languages for the CaptionML and Language properties.

  • XMLports support UTF-8 and UTF-16 formats for XML.

Note Note

With dataports, you can use the CurrFile object to read and write directly to the input or output file. XMLports do not have a CurrFile object.

Expand image Remarks

For more information about how to design XMLports, see Creating XMLports.

Expand image See Also

Reference

BREAK Function (Dataport, Report, XMLport)
EXPORT Function (XMLport)
FILENAME Function (Dataport, XMLport)
IMPORT Function (XMLport)
QUIT Function (Dataport, Report, XMLport)
RUN Function (XMLport)
SETTABLEVIEW Function (Dataport, Form, Report, XMLport)
SKIP Function (Dataport, Report, XMLport)


EXPORT Function (XMLport)

EXPORT Function (XMLport)
See Also
CollapseAll image

Creates an XML data stream (XML document) and sends it to a chosen destination.

[Ok :=] EXPORT(Number, OutStream[, Record])

Parameters

Number

Type: Integer

The ID of the XMLport that you want to run.

OutStream

Type: ISequentialStream

Where the XMLport object will write the XML data stream.

Record

Type: Record

The record to use in the XMLport. Any filters attached to the record will be used.

This parameter is optional.

Expand image See Also

Reference

XMLport Data Type


IMPORT Function (XMLport)

IMPORT Function (XMLport)
See Also
CollapseAll image

Reads and parses an incoming XML data stream (XML document).

[Ok :=] IMPORT(Number, InStream)

Parameters

Number

Type: Integer

The ID of the XMLport that you want to run.

If the XMLport that you specify does not exist, a run-time error occurs.

InStream

Type: ISequentialStream

The source from which the import XMLport object will read the XML data stream.

Expand image See Also

Reference

XMLport Data Type


RUN Function (XMLport)

RUN Function (XMLport)
See Also
CollapseAll image

Loads and executes the XMLport that you specify.

XMLport.RUN (Number [, ReqWindow] [, Record] [, Import])

Parameters

XMLport

Type: XMLport

The variable is automatically cleared after this function runs.

Number

Specifies the XMLport to run.

ReqWindow

Specify True to show request page; specify False to run the report and skip the request page.

The default is True.

Record

Tells the system which record to use in the XMLport. The system will use any filters that are attached to the specified record.

Import

Overrides the Direction property in metadata so that no direction control is shown on the request page. Specify True to run the XMLport and import data; specify False to export data.

The default is True.

Expand image See Also

Reference

XMLport Data Type


Properties

Properties

View the table of contents to see the complete list of properties that are available in Microsoft Dynamics NAV 2009.

See Also

Concepts

C/AL Functions
Triggers
Information


ActiveControlOnOpen Property

ActiveControlOnOpen Property

Sets the control that is activated when the form is opened.

Expand image Applies To

Forms

Expand image Remarks

Set this property to the ID Property of the control that should be activated when the form is opened. If this property is not set, the control in the upper left corner of the form is set as the active control by default.

If this property is set to an ID Property that is not present on the form, the default will be used and no error will occur.

Expand image See Also

Concepts

Properties


AltSearchField Property

AltSearchField Property

Sets the Name Property of an alternative field used to perform lookups on the current field.

Expand image Applies To

Fields

Expand image Remarks

This property makes it easier for users to use search and lookup in a table. For example, if a table's primary key is a numeric identifier that is also used as a foreign key in another table, users must know this identifier to perform a lookup into this table. Using this property, you can link a different search field that is easy to remember (for example, a name or address field) to the numeric primary key field.

Expand image See Also

Concepts

Properties


AssistEdit Property

AssistEdit Property

Sets assist-edit capabilities for a text box.

Expand image Applies To

  • Forms

  • Pages

  • Text boxes

Expand image Property Value

Yes if assist-edit capabilities and an AssistEdit button are provided; otherwise, No. The default value is No.

Expand image Remarks

You can add C/AL code in the OnAssistEdit Trigger to change the default assist-edit behavior.

Expand image See Also

Reference

Lookup Property
DrillDown Property
DropDown Property


AutoCalcField Property

AutoCalcField Property

Sets whether FlowFields should be automatically calculated. The source expression to this control must be a FlowField in the source table.

Expand image Applies To

  • Check boxes

  • Indicators

  • Option boxes

  • Picture boxes

  • Text boxes

Expand image Value Property

Yes if the FlowField is automatically calculated; otherwise, No. The default is Yes.

Expand image See Also

Reference

FlowFields


AutoCalcField Property (XMLports)

AutoCalcField Property (XMLports)
See Also
CollapseAll image

Sets the value FlowFields to indicate whether it should be recalculated before the field is exported.

Expand image Applies To

XMLports

Expand image Property Value

Yes if the FlowField is automatically calculated; otherwise, No. The default is Yes.

Expand image See Also

Reference

FlowFields


AutoEnter Property

AutoEnter Property

Determines whether the user entry is automatically accepted and focus is automatically moved to the next field. If Yes, the user does not have to press ENTER to move to the next field.

Expand image Applies To

Text boxes

Expand image Property Value

Yes if focus is moved to the next field after the maximum number of characters has been entered. No if the focus is in the current field until the user presses ENTER or ESC. The default is No.

Expand image See Also

Reference

NextControl Property


AutoFormatExpr Property

AutoFormatExpr Property

Sets a C/AL expression that specifies how to format data.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Remarks

The C/AL expression is evaluated when the expression performs updates. Together with the AutoFormatType Property, this property determines how data is formatted. These two properties are only used to format amounts that can be stated in a foreign currency.

When you use the AutoFormatType and AutoFormatExpr properties to format a field, a trigger called AutoFormatTranslate in code unit 1 is called. AutoFormatTranslate has ID 12 and takes two parameters: one from the AutoFormatType property and one from the AutoFormatExpr property. The AutoFormatType property contains an integer (0, 1, or 2) and the AutoFormatExpr property contains text (“ =LCY”).

These properties are used when you have an amount or a unit amount that you want to be able to display in another currency and these properties determine the number of decimals that will be displayed. For example, a sales order will use 2 decimals when the currency is defined as US dollar and 0 decimals when the currency is defined as IDR (Indonesian rupiah).

The settings for the AutoFormatType property and the AutoFormatExpr property depend on the type of data in the control or database field you need to format. There are three categories of data: amount, unit amount, and other types of data.

  • Amount - AutoFormatType must be 1 and AutoFormatExpr must return a currency code (the blank currency code denotes LCY) in order for data to be formatted as amount data.

  • Unit Amount - AutoFormatType must be 2 and AutoFormatExpr must return a currency code (the blank currency code denotes LCY) in order for data to be formatted as unit amount data.

  • Other - AutoFormatType must be 0 and AutoFormatExpr must be blank for data to be formatted using the default C/SIDE settings (Standard Format 0).

If the AutoFormatType property does not contain a value, the format specified in the DecimalPlaces Property will determine how the decimal is formatted in the table, report, or form. However, if you enter a value in the AutoFormatType property, it will override the value specified in the DecimalPlaces property and the AutoFormatType property will determine how the decimal is formatted in the table, report, or form. Furthermore, if you enter a value in the AutoFormatType property for a report or form, it will override the value entered in the DecimalPlaces property in the table and determine how the decimal is formatted in the report or form.

Expand image See Also

Reference

AutoFormatType Property
DecimalPlaces Property


AutoFormatType Property

AutoFormatType Property

Sets a value that determines how data is formatted, together with the C/AL expression in the AutoFormatExpr Property.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Remarks

These two properties are only used to format amounts that can be stated in a foreign currency. When you use the AutoFormatType and AutoFormatExpr properties to format a field, a trigger called AutoFormatTranslate in code unit 1 is called. AutoFormatTranslate has ID 12 and takes two parameters; one from the AutoFormatType property and one from the AutoFormatExpr property. The AutoFormatType property contains an integer (0, 1, or 2) and the AutoFormatExpr property contains text (“ =LCY”).

These properties are used when you have an amount or a unit amount that you want to be able to display in another currency and these properties determine the number of decimals that will be displayed. For example, a sales order will use 2 decimals when the currency is defined as US dollar and 0 decimals when the currency is defined as IDR (Indonesian rupiah).

The settings for the AutoFormatType property and the AutoFormatExpr property depend on the type of data in the control or database field you need to format. There are three categories of data: amount, unit amount, and other types of data.

  • Amount - AutoFormatType must be 1 and AutoFormatExpr must return a currency code (the blank currency code denotes LCY) in order for data to be formatted as amount data.

  • Unit Amount - AutoFormatType must be 2 and AutoFormatExpr must return a currency code (the blank currency code denotes LCY) in order for data to be formatted as unit amount data.

  • Other - AutoFormatType must be 0 and AutoFormatExpr must be blank for the data to be formatted using the default C/SIDE settings (Standard Format 0).

If the AutoFormatType property does not contain a value, the format specified in the DecimalPlaces Property property will determine how the decimal is formatted in the table, report, or form. If you enter a value in the AutoFormatType property, it will override the value specified in the DecimalPlaces property and the AutoFormatType property will determine how the decimal is formatted in the table, report or form. Furthermore, if you enter a value in the AutoFormatType property for a report or form, it will override the value entered in the DecimalPlaces property in the table and determine how the decimal

Expand image See Also

Reference

AutoFormatExpr Property


AutoIncrement Property

AutoIncrement Property

Sets whether the field value should be automatically incremented.

Expand image Applies To

Fields of Integer Data Type and BigInteger Data Type

Expand image Property Value

Yes if the field value is automatically incremented; otherwise, No. The default value is Yes.

Note Note

If you want to manually assign a value to a field that has the AutoIncrement property set to Yes, you must be member of the SQL Server db_owner database role.

Expand image Remarks

A table can only contain one auto-increment field. The numbers assigned to this field will not always be consecutive for the following reasons:

  • If you delete some records from a table, the numbers used for these records are not reused.

  • If several transactions are performed at the same time, they will each be assigned a different number. However, if one of these transactions is rolled back, the number that it was assigned is not reused.

If you add an auto-increment field to an existing table, the field automatically generates consecutive values and inserts them into the table. If you enable the AutoIncrement property for a field that already contains data, there must be no zero values in the field.

The AutoIncrement property is designed to always assign numbers automatically. If you want to insert a record, be sure that the value in this field is blank before you insert the record. This is even more critical when you are using the SQL Server Option.

The AutoIncrement property does not work with C/SIDE temporary tables.

Expand image See Also

Concepts

Properties


AutoPosition Property

AutoPosition Property

Set to indicate where the form is positioned on the screen when opened.

Expand image Applies To

Forms

Expand image Property Value

Value | Description
CenterScreen | Center the form on the screen
CenterActiveForm | Center the form with respect to the active form
OutsideActiveForm | Place the form outside the active form
OutsideActiveControl | Place the form outside the active control
None (default) | No position specified

Expand image Remarks

If you choose None, the XPos Property and YPos Property determine where to place the form. If you choose another setting, the XPos and YPos property values are ignored. If the form is displayed in lookup mode, it is automatically placed outside the active control.

This property is evaluated when the form is opened and does not affect the placement of any related subforms.

Expand image See Also

Reference

XPos Property
YPos Property


AutoRepeat Property

AutoRepeat Property

Sets the action when the user presses and holds down the mouse button.

Expand image Applies To

Command buttons

Expand image Property Value

Yes if the action is repeated when the user presses and holds down the mouse button; otherwise, No. The default value is No.

Expand image See Also

Reference

PushAction Property


AutoReplace Property

AutoReplace Property

Sets whether imported records automatically replace existing records with the same primary key.

Expand image Applies To

Data items (in dataports)

Expand image Property Value

Yes if the records are replaced; otherwise, No. The default value is No.

Expand image See Also

Concepts

Properties


AutoSave Property

AutoSave Property

Sets whether imported records are automatically inserted into the table.

Expand image Applies To

Data items (in dataports)

Expand image Property Value

Yes if the record is inserted automatically; otherwise, No. The default value is Yes.

Expand image Remarks

If AutoSave is set to No, then imported records are not automatically inserted into the appropriate tables. To insert records manually, use the OnAfterImportRecord Trigger. For example, use the OnAfterImportRecord Trigger if you need to evaluate the records before inserting them, or if you want to calculate or retrieve additional data before inserting the record.

If a record already exists and AutoSave is set to Yes, the value of the AutoReplace Property determines whether the imported record overwrites the existing record.

Expand image See Also

Reference

OnAfterImportRecord Trigger
AutoReplace Property


AutoSplitKey Property

AutoSplitKey Property

Sets whether a key is automatically created for a new record placed between the current record and the previous record.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if the key is automatically created for the new record; otherwise, No. The default value is No.

Expand image Remarks

To set this property to a value of Yes, the following conditions must be met:

  • The current key must be the primary key.

  • The last field in the primary field must be an Integer Data Type, BigInteger Data Type, GUID Data Type, or Decimal Data Type field.

Expand image See Also

Concepts

Properties


AutoUpdate Property

AutoUpdate Property

Sets a value that indicates whether imported records are initialized with values from an existing record with the same primary key.

Expand image Applies To

Data items (in dataports)

Expand image Property Value

Yes if the records are initialized; otherwise, No. The default value is Yes.

Expand image Remarks

When AutoUpdate is set to Yes, empty fields in the imported record are automatically updated with values from an existing record that has the same primary key.

Set AutoUpdate to Yes when you import a file with partial information. For example, you can use this property if you create new prices for an item list in an external file where this file only contains item numbers and prices. In this case, you would want to update the price field, while retaining the information in the other fields.

Expand image See Also

Concepts

Properties


BackColor Property

BackColor Property

Sets the background color of the control.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

Use the Color option on the View menu to select a color or enter the RGB Color Model value of the color you want for the background.

The default is the system background color.

Expand image See Also

Reference

ForeColor Property
BackTransparent Property


BackTransparent Property

BackTransparent Property

Sets the background to be transparent. If you set this property to Yes, the BackColor Property setting is ignored.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Indicators

  • Labels

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Yes if the BackColor setting is ignored and the background is made transparent; otherwise, No. The default is Yes for labels, images, check boxes, option buttons, picture boxes, indicators, frames, and tab controls. The default is No for command buttons, menu buttons, and table boxes.

Expand image See Also

Reference

ForeColor Property


BackupKey Property

BackupKey Property

This property is used by the backup/restore system. Under normal circumstances, you do not need to set this property.

Expand image Applies To

Keys

Expand image Property Value

Yes if the enabled property of secondary keys will be restored during restore; otherwise, No. The default value is No.

Expand image Remarks

During backup, secondary keys where the Enabled Property is set to a value of Yes are marked with a BackupKey value of Yes, and the secondary indexes are not stored in the backup. When the backup is restored, the BackupKey value is checked to see whether it reenables secondary keys where BackupKey = Yes, and the indexes are recreated.

You will normally only see the BackupKey set to No (the default), as it is only set to Yes during backup. If a backup restore is suspended during key creation (to be resumed at a later time), you can see and set the BackupKey property.

Expand image See Also

Reference

Enabled Property


Bitmap Property

Bitmap Property

Sets a bitmap to use for a label, command button, menu button, check box, or option button.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Labels

  • Menu buttons

  • Option buttons

Expand image Remarks

Enter the filename of the bitmap you want to use, for example: c:\pictures\thisone.bmp.

There are 44 predefined bitmaps. They can be chosen by entering a number from 1 to 44. The bitmap will be imported once specified. If you change the bitmap, you will have to re-import it if you want to update the version that is used. You can do this by reentering the value in this property.

The maximum size of a bitmap is 32 KB. Use a BLOB field for larger bitmaps.

Expand image See Also

Reference

BitmapList Property
BitmapPos Property
BLOB Data Type


BitmapList Property

BitmapList Property

Sets a list of bitmaps from which the correct bitmap to display is selected.

Expand image Applies To

Picture boxes

Expand image Remarks

Specify the bitmap list using a comma-separated list of file names, such as c:\pictures\foo.bmp,c:\pictures\bar.bmp. There are 44 predefined bitmaps. They can be chosen by entering a number from 1 to 44. You can mix external bitmaps that are stored in files, with the internal bitmaps in this list.

The SourceExpr Property of the control is used to choose which bitmap to display. The first bitmap in the list is number 1, the second bitmap is number 2, and so on.

The bitmaps are imported. If you change one or more of the bitmaps, you have to re-import them to update the versions that are used. You can do this by reentering this property value.

The size limit for all the user-defined bitmaps included in the list is 32 KB.

Expand image See Also

Reference

Bitmap Property
BitmapPos Property


BitmapPos Property

BitmapPos Property

Sets the position of a bitmap.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Menu buttons

  • Option buttons

Expand image Property Value

Value | Description
None | None (the bitmap is not displayed)
Left (default for command buttons, check boxes, option buttons) | On the left
Right (default for menu buttons) | On the right
Top | At the top
Bottom | At the bottom
Center | In the center

Expand image See Also

Reference

Bitmap Property
BitmapList Property


BlankNumbers Property

BlankNumbers Property

Indicates whether the system will clear a range of numbers as it formats them.

Expand image Applies To

  • Forms

  • Pages

  • Text boxes

Expand image Property Value

Value | Description
DontBlank (default) | Not clear any numbers
BlankNeg | Clear negative numbers
BlankNegAndZero | Clear negative numbers and zero
BlankZero | Clear numbers equal to zero
BlankZeroAndPos | Clear positive numbers and zero
BlankPos | Clear positive numbers

Expand image See Also

Reference

BlankZero Property


BlankZero Property

BlankZero Property

Indicates whether the system displays zeros (0) and No.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Property Value

Yes if zeros and No are displayed; otherwise, No. The default is No.

Expand image Remarks

The setting for the text box overrides the setting for the field on the current form.

Expand image See Also

Reference

BlankNumbers Property


Border Property

Border Property

Sets a value that indicates whether a border is displayed around the control.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Yes if a border is displayed; otherwise, No. The default is Yes for command buttons, menu buttons, text boxes, picture boxes, indicators, frames, tab controls, and table boxes. The default is No for labels, images, check boxes, option boxes, and text boxes in a report.

Expand image See Also

Reference

BorderColor Property
BorderStyle Property
BorderWidth Property


BorderColor Property

BorderColor Property

Sets the color for the border. This property only applies if Border Property is set to Yes.

Expand image Applies To

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Picture boxes

  • Shapes

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

Use the Color option on the View menu to select a color or enter the RGB Color Model value of the color you want for the border. The default is the system border color.

BorderColor is only applied when you are running Windows Classic style (not Windows Themes) and BorderStyle Property is set to Normal.

Expand image See Also

Reference

BorderStyle Property
BorderWidth Property


BorderStyle Property

BorderStyle Property

Sets the type of border to display around the form or control.

Expand image Applies To

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Forms:

Value | Description
Single (default) | A single line
Double | A double line
None | No border

Controls:

Value | Description
Normal (default for labels, images, shapes, subforms) | A single line
Raised (default for frames, tab controls) | Raised
SemiSunken (default for picture boxes, indicators and non editable text boxes) | Semi-sunken
Sunken (default for table boxes and editable text boxes) | Sunken
BumpUp | Bumped up
BumpDown | Bumped down

Expand image Remarks

For controls, you can only use this property if the Border Property property is set to Yes.

For controls, you can use the Color option on the View menu to select a border style or choose one of the values shown above.

Expand image See Also

Reference

BorderColor Property
BorderWidth Property


BorderWidth Property

BorderWidth Property

Sets the width of the border around the frame.

Expand image Applies To

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Picture boxes

  • Shapes

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Value | Description
Hairline (default) | Hairline border
1pt | One point (1 pt.) border
2pt | Two point (2 pt.) border
3pt | Three point (3 pt.) border
4pt | Four point (4 pt.) border
 | and so on

Expand image Remarks

Use the Color option on the View menu to select a border width or choose one of the values shown above.

BorderWidth is only applied when you are running Windows Classic style (not Windows Themes) and BorderStyle Property is defined as Normal.

Expand image See Also

Reference

BorderColor Property
Border Property


BottomMargin Property

BottomMargin Property

Sets the bottom margin of a report. The unit of measure is 1/100 milimeters.

Expand image Applies To

Reports

Expand image Remarks

A bottom margin specified in the page setup dialog overrides the value of BottomMargin.

Some printers require a minimum margin. If you specify a margin that is smaller than the minimum margin, the minimum margin is used when printing.

The default value is 20 milimeters.

The BottomMargin property is not supported on client report definition (RDLC) report layouts. The create layout suggestion function sets the margin values for RDLC report layouts.

Expand image See Also

Concepts

Properties


CalcFields Property

CalcFields Property

Sets a list of FlowFields to automatically calculate.

Expand image Applies To

  • Dataports

  • Forms

  • Reports

  • XMLports

Expand image Remarks

Use the AssistEdit button to select the FlowFields.

Expand image See Also

Concepts

Properties


CalcFormula Property

CalcFormula Property

Sets the calculation for FlowFields.

Expand image Applies To

Fields

Expand image Remarks

You can choose from several methods of calculations including sum (total), average, maximum value, minimum value, record count, lookup, and whether a record exists. Use the AssistEdit button to set up the calculation formula. The AssistEdit window lets you reverse the calculation, choose a table and fields, and create filters.

Expand image See Also

Reference

FlowFields


CallFieldValidate Property

CallFieldValidate Property

Sets a value that indicates whether the OnValidate (Fields) Trigger is executed when a field is imported.

Expand image Applies To

Dataports

Expand image Property Value'

Yes if the trigger is executed; otherwise. No. The default value is No, unless the FileFormat Property is set to a value of UPXML for User Portal dataport. In this case, the default value of the CallFieldValidate property is Yes.

Expand image Remarks

Imported fields are validated in the same order that they appear in Field Designer. The code in the OnValidate (Fields) Trigger might initialize other fields in the record. If this is the case, investigate whether the order that fields are validated is important by looking at the OnValidate triggers of those fields.

Expand image See Also

Reference

FileFormat Property
OnValidate (Fields) Trigger


Cancel Property

Cancel Property

Sets a value that determines whether users can activate the command button by pressing the ESC key.

Expand image Applies To

Command buttons

Expand image Property Value

Yes if you want ESC to activate or push this command button; otherwise, No. The default value is No.

Expand image Remarks

This property only applies to the first command that is received after the user opens the form. When the user presses the ENTER or ESC key, a specified response is checked for. The default and cancel properties are only executed if there is no specified response.

Expand image See Also

Reference

Default Property


Caption Property

Caption Property

Sets the caption in the current language.

Expand image Applies To

  • Check boxes

  • Codeunits

  • Command buttons

  • Dataports

  • Fields

  • Forms

  • Frames

  • Indicators

  • Labels

  • Menu buttons

  • Menu items

  • Option buttons

  • Pages

  • Picture boxes

  • Reports

  • Tables

  • Text boxes

  • XMLports

Expand image Remarks

This value is taken from the CaptionML Property property if this property is set. A caption is the text used to show the identity of a control (for example, in the caption bar of a form or a label for another control).

Expand image See Also

Reference

ShowCaption Property

Concepts

Working with Multilanguage Functionality


CaptionBar Property

CaptionBar Property

Sets the type of caption bar to be displayed.

Expand image Applies To

Forms

Expand image Property Value

Value | Description
Normal (default) | Normal
Narrow | Narrow
None | No caption bar

Expand image Remarks

This setting is checked when the form is opened. The value of this property on the form does not affect the caption bar type used by subforms.

Expand image See Also

Concepts

Properties


CaptionClass Property

CaptionClass Property

Controls the caption that is used in the label of a field in a database table or in the label of a control on a form.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

The data type of the C/AL expression must be either Text (maximum length 80) or Code.

Because this property allows you to enter an expression, C/SIDE must be able to differentiate between a literal string like 'DIM1' and a variable or function called DIM1. Every text string that you enter must be enclosed in ' ' or it will be interpreted as a variable or function. You need to enter a value that results in a string. For example, if you want to enter 1 + 5, you must either enter '1+ 5', or FORMAT(1 + 5), which results in '6'.

The expression is then interpreted by trigger 15 in codeunit 1.

C/AL expression | Comments
DIM1 | This value produces an error unless a text variable exists with the name DIM1.
'DIM1' | OK. The caption is 'DIM1.'
'DIM'+FORMAT(2) | OK. The caption is 'DIM2.'
1+5 | Error. The data type is Integer

Expand image See Also

Concepts

CaptionClass Functionality


CaptionML Property

CaptionML Property

Sets the string that is used to identify a control or other object in the user interface.

Expand image Applies To

  • Check boxes

  • Codeunits

  • Command buttons

  • Dataports

  • Fields

  • Forms

  • Frames

  • Indicators

  • Labels

  • Menu buttons

  • Menu items

  • Option buttons

  • Pages

  • Picture boxes

  • Reports

  • Tables

  • Text boxes

  • XMLports

Expand image Remarks

The CaptionML property is multilanguage enabled, so it can contain a list of text strings in different languages. The string that is used is selected according to the user's language settings. For more information, see Working with Multilanguage Functionality.

The CaptionML property has the following format.

<Language ID>=<caption>

<Language ID> is the standard Windows three-letter language ID, and <caption> is the caption text for this language. Use semicolons to separate entries.

The following example shows a CaptionML value.

DAN=Navn;DEU=Name;ESP=Nombre;FRA=Nom

In this example, values are set for Danish (DAN), German Standard (DEU), Spanish Traditional Sort (ESP), and French Standard (FRA).

You can enter values for the CaptionML property in two ways:

  • If you enter a value for the Caption Property, then the CaptionML property is set to the value of the current language. For example, if the current system language is Danish, then a value of DAN =<value> is placed in the CaptionML field.

  • If you click the AssistButton in the CaptionML value field, then the Multilanguage Editor opens and displays two columns: Language and Value. The Language column is populated with all languages that are defined by Windows. You specify the CaptionML value for a language by entering a value in the Value field for that language. You need to close this form by clicking OK. If you press ESC to close this form, then the CaptionML field is not updated.

The following table shows how the default caption is determined for the various objects in C/SIDE.

Object | Default caption
Table | Name property
Field | Name property
Codeunit | Name property
Form | Name property
Report | Name property
Dataport | Name property
XMLport | Name property
Command button and menu item | PushAction or Name property
Menu button, indicator, text box, picture box, and frame | Name property
Check box | OptionValue or Name property

Label Controls

The Caption Property of a label control is automatically set to the Caption Property of the parent control (as specified by the ParentControl Property of the label). When you add labels to a form by using a form wizard or by selecting the Add Label check box in the Toolbox when a control is inserted, the parent control is set by default. If a label control does not have a parent control, then the Name Property of the label control is used as the caption.

When a label has a parent control and this parent control is related to a table, the caption will be taken from the first available value in following list:

  1. The CaptionML of the label itself.

  2. The CaptionML of the parent control.

  3. The CaptionML of the table field that the parent control relates to.

  4. The Name property of the parent control.

  5. The Name property of the table field that the parent control relates to.

  6. The Name property of the label itself.

For example, the CaptionML property for a database field with the name "Name" contains:

DAN=Navn,DEU=Name,FRA=Nom

You create a text box with a label for this field where the label has the text box as its parent control. You do not set a value for the Caption field of the CaptionML property of the label. The label will get the caption "Navn" if the user selects Danish as the language, "Name" for German, and "Nom" for French (rule 3). If you delete the CaptionML values for the database field, then the user will see "Name" as the caption of the label no matter what language is selected (rule 5).

Expand image See Also

Reference

Caption Property
ParentControl Property
Name Property


CardFormID Property

CardFormID Property

Sets the card page that is associated with items in the current list page.

Expand image Applies To

Pages

Expand image Remarks

This property replaces the Card-to-List functionality in Microsoft Dynamics NAV 5.0. Use this property on a list page to specify the card page that should be displayed when an end user double-clicks an item on the list page. For an example of how the CardFormID property is used, see Walkthrough: Creating a Customer List in Page Designer.

Expand image See Also

Tasks

Walkthrough: Creating a Customer List in Page Designer


CharAllowed Property

CharAllowed Property

Sets the range of characters the user can enter into this field or text box.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Remarks

If you want users to only enter uppercase letters in this field, enter AZ. This ensures that only uppercase characters in the range of A-Z are accepted. If you want both uppercase and lowercase characters, leave this value blank.

You can specify multiple ranges of characters by entering the parameters in pairs. For example, a value of admpzz indicates that only the following characters are accepted: a, b, c, d, m, n, o, p, and z. If you only want to allow a single character, then enter that character twice to specify a starting and ending range.

For text boxes, you can use this property to further limit the characters allowed, based on the field's setting.

The setting for the text box and the field is checked during validation.

Expand image See Also

Concepts

Properties


ChartPartID Property

ChartPartID Property

Sets the ID of the chart to add to the page.

Expand image Applies To

  • Pages

  • Subtype - UIPartType

  • Type - Control

Expand image Remarks

To set this property, you need to first set the value of the PartType Property to Chart. The ChartPartID property creates a link to the selected chart in the Charts table.

Expand image See Also

Reference

PartType Property
PagePartID Property
SystemPartID Property


ClearOnLookup Property

ClearOnLookup Property

Sets a value that determines whether the current contents of the field are deleted before the value that is selected via the lookup is added.

Expand image Applies To

  • Fields

  • Text boxes

Expand image Property Value

Yes if current contents of the field are replaced; otherwise, No if the contents are pasted. The default value is Yes for all fields except FlowFilters fields.

Expand image See Also

Reference

FlowFilters


ClosingDates Property

ClosingDates Property

Sets a value that determines whether users can enter a closing date in this field. The default value is No.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Remarks

All dates have a corresponding closing date. A closing date is a period following the given date, but before the next date. Closing dates are sorted immediately after the corresponding date but before the next date.

For fields, this property only applies to Date and Time Functions.

For text boxes and fields, the value of this property is checked during validation.

Expand image See Also

Concepts

Date and Time Functions


Clustered Property

Clustered Property

Sets a value that indicates whether the index is clustered.

Expand image Applies To

Keys

Expand image See Also

Concepts

Properties


Compressed Property

Compressed Property

Sets a value that specifies whether a BLOB is compressed.

Expand image Applies To

Fields of the BLOB Data Type

Expand image Remarks

Note Note

This property only applies to the Microsoft SQL Server Option for Microsoft Dynamics NAV.

If you want to access BLOB data with an external tool, for example to display a bitmap, you must set this property to No.

The Microsoft Dynamics NAV client and C/FRONT can both access BLOBs without using this property.

Expand image See Also

Reference

BLOB Data Type


ContainerType Property

ContainerType Property

Sets the ContainerType property in Page Designer when you want to add one of the following controls to a page:

  • Container

  • Group

  • Field

  • Part

Expand image Applies To

  • Pages

Expand image Remarks

When you select ContainerType in page designer you can also choose from one of the following subtypes:

  • ContentArea

  • FactBoxArea

  • RoleCenterArea

Expand image See Also

Concepts

Properties


ControlAddin Property

ControlAddin Property

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Sets the RoleTailored client control add-in to use on the field control.

Expand image Applies To

Field controls on pages.

Expand image Property Value

The name and public token key of the control add-in as registered in the Control Add-in table (ID 2000000069). For more information, see How to: Register a RoleTailored Client Control Add-in.

Expand image Remarks

A control add-in is a custom control, or visual element, for displaying and modifying data on RoleTailored client pages.

Expand image See Also

Tasks

Walkthrough: Creating and Using a RoleTailored Client Control Add-in

Concepts

RoleTailored Client Control Add-in Overview
Installing and Configuring RoleTailored Client Control Add-ins on Pages
Developing RoleTailored Client Control Add-ins


ControlType Property

ControlType Property

Use this property when you select a control type in Page Designer.

Expand image Applies To

This property displays the following control types for you to choose from:

  • Container

  • Group

  • Field

Expand image See Also

Concepts

Properties


Data Type Property

Data Type Property

Sets the data type of a table field.

Expand image Applies To

Fields

Expand image See Also

Concepts

Properties


DataCaptionExpr Property

DataCaptionExpr Property

Sets a C/AL expression that is evaluated and displayed to the left of the form caption.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

The expression is evaluated each time the user switches from one record to another or when one of the fields in the record changes.

Expand image See Also

Concepts

Properties


DataCaptionFields Property

DataCaptionFields Property

Sets the fields that appear to the left of the caption on forms or pages that display the contents of this table.

Expand image Applies To

  • Forms

  • Pages

  • Tables

Expand image Remarks

Card Forms

Card forms and pages display one record at a time. For these objects, the value of the underlying table's DataCaptionFields property is used; the value of this property on the form or page is ignored. If the DataCaptionFields property is not defined on the table, the primary key is used.

Tabular Forms

Tabular forms and pages show multiple records at a time. The following data caption rules are applied:

  • A data caption is only displayed if a filter containing the fields defined in the DataCaptionFields property for the form or page evaluate to one value. In this case, two situations are possible:

    • There is a table relation (as defined by the TableRelation Property) on one or more of the fields. In this case, the DataCaptionFields from the underlying table are used. If this table does not have a value for the DataCaptionFields property, the primary key for that table is used.

    • There is no table relation. In this case, the (single) value that results from evaluating the filter is used directly.

A form is considered a tabular form when the TableBoxID Property of the form is not blank.

Example of DataCaptionFields Use

The following is an example of how the DataCaptionFields property is used. The Customer Card form (21) is based on the Customer table (18). Using the Customer menu on this form, users can open other forms, including the Customer Ledger Entry form (25) and the Customer List form (22). The Customer List form is invoked using the Lookup Table menu item.

In the Customer table, the DataCaptionFields property is set to No., Name. On the Customer Ledger Entry form, the DataCaptionFields property is set to Customer No.. When the Customer Ledger Entry form (25) is opened from the Customer Card form (21), a filter is set on Customer No. field of the Customer Ledger Entries table, selecting only those entries related to the currently displayed customer on the Customer Card. This relationship is accomplished by setting the RunFormLink property of the menu item that invokes the Customer Ledger Entry form to Customer No.=FIELD(No.).

If you view the Customer Ledger Entry form with a filter applied, the customer name and number appear to the left of the caption on the Customer Ledger Entry form. If you remove the filter, the caption disappears. Next, open the Customer List form from the Customer menu on the Customer Card. No caption is displayed because all customers are shown and no filter is set. Set a filter on the Customer No. field to restrict the form to show only one customer. No caption appears because no DataCaptionFields are defined for the Customer List form.

This example does not cover all the possible situations, but should provide some idea about how this property is used. The important point is that the DataCaptionFields property on a form does not directly put any caption on the form, but only works when used with appropriate settings of DataCaptionFields at the table level.

Expand image See Also

Concepts

Properties


DataItemIndent Property

DataItemIndent Property

Sets the indentation level of a data item.

Expand image Applies To

  • Data items

  • Reports

Expand image Remarks

A value of <0> (zero) indicates no indentation. Data items can be indented ten levels deep. The largest possible value of this property is <10>. You can only indent a data item one level at a time, so the indentation level of a data item can be no more than one greater than the level of the preceding data item. Usually, you will set the indentation level property from the Report Designer, where data items can be indented by clicking a button.

When a report is run, the first data item is processed. If there is an indented data item (second data item), it is processed each time a record is retrieved and processed in the first data item. This process is recursive, meaning that if there is a third data item with additional indentations after the second data item, then this third data item is processed in the same way as the second items was processed with regard to the top-level data item, and so on.

You can also indent data items in dataports. Only dataports with the FileFormat Property set to a value of UPXML can be compiled with indented data items.

Expand image See Also

Reference

FileFormat Property


DataItemLink Property

DataItemLink Property

Sets the corresponding fields from two data items that are linked by the DataItemLinkReference Property. The link is defined as a property of the indented (child) data item.

Expand image Applies To

  • Data items

  • Reports

Expand image Remarks

The following syntax shows the DataItemLink property.

<field>=FIELD(<reference field>)

The following table describes field and reference field.

Syntax | Description
<field> | A field from the child data item
<reference field> | A field from the less indented (parent) data item that is identified by the DataItemLinkReference Property

The DataItemLink property sets a filter on the child data item. This filter selects records that contain the same field value in both the parent and child data items. Use the AssistButton to select the fields from field name lookups for the parent and child data items.

The following example illustrates using this property. You have two data items, a parent and child. The parent data item is a list of customers, called Customer. The child data item contains a record of all sales orders. In the customer table, the primary key is the customer number, which is stored in the No. field. In the table that contains sales data, each record contains this customer number as a foreign key in a field called Sell-to Customer No. You set the value of the DataItemLinkReference Property on the child data item to the parent data item. You set the DataItemLink property of the child data item to the following value.

Sell-to Customer No.=FIELD(No.)

You now have a filter on the records in the child data item. This filter only displays records that pertain to the currently selected customer record. You can also accomplish the same task by placing the following C/AL statement in the OnPreDataItem Trigger for the child data item.

CopyCode image Copy Code
SETRANGE("Sell-to Customer No.",Customer."No.");

Expand image See Also

Reference

OnPreDataItem Trigger
DataItemLinkReference Property


DataItemLinkReference Property

DataItemLinkReference Property

Sets the parent data item to which a child (indented) data item is linked. After you specify the DataItemLinkReference value, use the DataItemLink Property to specify a field from each data item on which to base the link.

Expand image Applies To

  • Data items

  • Reports

Expand image Remarks

The value of the DataItemLinkReference property must be specified as the DataItemVarName Property of the parent data item.

The default value is the name of the last preceding data item in the report with lower indentation. You can set DataItemLinkReference and DataItemLink properties for a data item that is not a child of another data item, however, this will not have any effect.

Expand image See Also

Reference

DataItemVarName Property


DataItemSeparator Property

DataItemSeparator Property

Sets the string used to separate data items.

Expand image Applies To

Dataports

Expand image Property Value

Value | Description
<None> | No DataItemSeparator
<NewLine> | Any combination of carriage return (CR) and line feed (LF) characters
<CR/LF> | CR followed by LF
<CR> | CR alone
<LF> | LF alone
<TAB> | Tabulator alone
Other strings | Specified string

Expand image Remarks

Strings must be entered using the < and > characters to enclose the string. These special strings can be combined, and also be mixed with other characters.

The default value is <NewLine><NewLine>.

CR refers to the character with ASCII value 13 and LF refers to the character with ASCII value 10.

Expand image See Also

Concepts

Properties


DataItemTable Property

DataItemTable Property

Gets the name of the database table that a data item is based on.

Expand image Applies To

Data items

Expand image Remarks

This property is set automatically when you use the Report Designer or Dataport Designer to create data items.

If you have two data items based on the same table, you must specify a different name for one of the data items in the DataItemVarName Property.

Expand image See Also

Reference

DataItemVarName Property


DataItemTableView Property

DataItemTableView Property

Sets the key, sort order, and filter for the data item.

Expand image Applies To

Data items

Expand image Remarks

Use the AssistButton to select the key, sort order, and filter that you want to use.

  • If you select a key, the report or dataport users cannot select a key, sort order, or filters for the data item.

  • If you select a sort order, this sort order is suggested as the default when report or dataport users select a sort order.

  • If you select a filter, this filter is used with user-specified filters in the request form.

  • Selecting a sort order, a filter, or both, does not prevent users from selecting a key.

Expand image See Also

Concepts

Properties


DataItemVarName Property

DataItemVarName Property

Sets a name for a data item.

Expand image Applies To

Data items

Expand image Remarks

This name can be used to refer to a record from the data item (when writing C/AL code in a trigger) or to the data item itself in the DataItemLinkReference Property. The default value is the name of the DataItemTable Property. There cannot be two data items with the same name in a report or dataport.

Expand image See Also

Reference

DataItemTable Property
DataItemLinkReference Property


DataLength Property

DataLength Property

Sets the maximum length of data stored in this field.

Expand image Applies To

Fields

Expand image Remarks

For Text Data Type and Code Data Type fields, enter the maximum length of the field. The database only stores the actual content of the field—not the maximum length you specify.

This field does not apply to the other data types because they have fixed lengths.

Expand image See Also

Reference

Text Data Type
Code Data Type


DataPerCompany Property

DataPerCompany Property

Sets a value that indicates whether the table data applies to all companies in the database or only the current company.

Expand image Applies To

Tables

Expand image Property Value

Yes if data is available only to this company; otherwise, No. The default value is Yes.

Expand image See Also

Concepts

Properties


DateFormula Property

DateFormula Property

Sets a date formula used to verify that the date the user enters is correct.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Remarks

The following table shows the syntax used to create the date formula.

Syntax | Description
30D | 30 days
2W | 2 weeks
CM+10D | Current month plus 10 days
CM+1M | Current month plus one month
CQ+1M+20D | Current quarter plus one month plus 20 days
CW+1W | Current week plus one week
D15 | On the 15th of each month

In Microsoft Dynamics NAV, weeks begin on Monday and end on Sunday.

For fields, this property only applies to text and code fields.

The text box and field settings are checked during validation.

Note Note

We do not recommend that you use this property, but use the DateFormula Data Type instead.

Expand image See Also

Reference

DateFormula Data Type


DecimalPlaces Property

DecimalPlaces Property

Sets display and storage requirements for the Decimal Data Type.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Property Value

You can enter minimum, maximum, or both values for the number of decimal places, as shown in the following examples.

Value | Description
1 | A minimum of 1 and a maximum of 1 decimal place
1:4 | A minimum of 1 and a maximum of 4 decimal places
2: | At least 2 decimal places
:2 | No more than 2 decimal places

Expand image Remarks

For decimal fields, this property specifies the number of decimal places that you want to store. The default storage requirements for Decimal Data Type are two decimal places for amounts. Use this property to specify storage requirements that are different than the default.

For text boxes, use this property to limit the number of decimal places that appear based on the setting for the field. You cannot increase the number of decimal places beyond what is set for the field. If the setting for the field is greater than the setting for the text box, then the setting for the text box is used to determine how to round the number.

Note Note

For text boxes, you can change this property setting at run time with C/AL code.

This setting is evaluated on text boxes and fields during validation.

When you create a new field of Decimal Data Type, the value is automatically formatted as a currency. If your decimal field does not contain a currency value, then you can use this property to determine the number of decimal places that appear on the screen. For example, in the G/L Entry table, the DecimalPlaces property of field 42, Quantity, is set to 0:5. The minimum number of decimal places that you can enter is 0 and the maximum is 5.

Expand image See Also

Reference

Decimal Data Type


Default Property

Default Property

Sets this command button as the default command button.

Expand image Applies To

Command buttons

Expand image Property Values

Yes if you want this command button to be the default; otherwise, No. The default is No.

Expand image Remarks

When a command button is chosen as the default, it is selected when the user presses ENTER or double clicks the mouse. This only applies to the first command that is received after the user opens the form. When the user presses ENTER or ESC, the system first checks to see if there is a specified response. The default property and Cancel Property are only executed if no response occurs.

Expand image See Also

Reference

Cancel Property


DefaultFieldsValidation Property

DefaultFieldsValidation Property

Sets a value that indicates whether fields are validated.

Expand image Applies To

XMLports

Expand image Property Value

Yes if fields are validated; otherwise, No. The default value is Yes.

Expand image Remarks

This property sets the default value of the FieldValidate Property. Therefore, if you change the setting of the DefaultFieldsValidation property, the change is implemented for all fields. However, for fields for which the FieldValidate property has been set to Yes or No, no change is made.

If you change the value of the FieldValidate property, the change does not affect the value of the DefaultFieldsValidation property. This means that FieldValidate can override DefaultFieldsValidation, but that it can also inherit the default value of DefaultFieldsValidation.

Expand image See Also

Concepts

Properties


DelayedInsert Property

DelayedInsert Property

Sets a value that specifies whether a must user leaves a record before it is inserted into the database. By default, new records are inserted when the user leaves the control that shows the primary key in the table.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if the record is inserted when the user leaves the record; otherwise, No if the record is inserted when the user leaves the control that shows the primary key. The default value is No.

Expand image See Also

Concepts

Properties


DeleteAllowed Property

DeleteAllowed Property

Sets a value that specifies whether users can delete records while using the form or page.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if the user can delete records; otherwise, No. The default value is Yes.

Expand image See Also

Concepts

Properties


Description Property

Description Property

Sets the description of the table, field, form, report, or control. This description is for internal use and does not appear to end users.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Fields

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Pages

  • Picture boxes

  • Reports

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Tables

  • Text boxes

Expand image See Also

Concepts

Properties


DeviceFontName Property

DeviceFontName Property

Sets a device font for a printer.

Expand image Applies To

Classic report layouts

Expand image Remarks

Use this property for reports that are specifically designed for dot matrix printers to prevent the printer from switching into graphics mode when printing text. Specify the name of a device font (a font that is built into a printer). Use the AssistButton to select a device font from the list of device fonts supported by a particular printer.

If the printer that is used for this report does not support the specified DeviceFontName or if DeviceFontName is set as Undefined, Helvetica is used.

A device font specified in the page setup dialog overrides the value of DeviceFontName.

Expand image See Also

Concepts

Properties


Dimensions Property

Dimensions Property

Sets the dimensions of a variable that is to create a multi-dimensional variable (array).

Expand image Applies To

Variables

Expand image Remarks

Enter the dimensions as a semicolon-delimited list of integers, where each number defines the number of elements in that dimension. The maximum number of dimensions is 10 and the total number of elements in all dimensions is 1,000,000.

For example, to define an integer array with dimensions 3 x 3 x 4, start by creating an integer variable called A. In the Properties window, set the Dimensions property to a value of 3;3;4. To access the elements in the array, use the following syntax:

A[2][3][2]

Indexes start at a value of 1 (not 0 as in some programming languages).

Expand image See Also

Concepts

Properties


Direction Property

Direction Property

Sets the XMLport to import, export, or import and export data in XML format.

Expand image Applies To

XMLports

Expand image Property Value

Value | Description
Import | Import
Export | Export
Both (default) | Import and export

Expand image See Also

Concepts

Properties


Divisor Property

Divisor Property

Sets a value that enables you to display a number as a multiple of another number.

Expand image Applies To

Text boxes

Expand image Remarks

This property enables you to display a number as a multiple of another number. For example, if you enter a value of 1000, then 13,000 is displayed as 13. The value in the database is not changed.

Expand image See Also

Concepts

Properties


DrillDown Property

DrillDown Property

Sets a drill-down for a text box.

Expand image Applies To

  • Forms

  • Pages

  • Text boxes

Expand image Property Value

Yes if a drill-down for the text box is provided; otherwise, No. The default value is No.

Expand image Remarks

Drill-downs are a system-wide feature of FlowFields that let you see the underlying transactions that make up the information shown in the FlowField. For example, if the FlowField shows an account balance, then providing a drill-down for this text box allows the user to quickly see the various transactions that make up the balance shown in the field.

Expand image See Also

Reference

OnDrillDown Trigger


DrillDownFormID Property

DrillDownFormID Property

Sets the ID of the form to use as a drill-down.

Expand image Applies To

  • Forms

  • Pages

  • Tables

  • Text boxes

Expand image Remarks

Drill-downs are a system-wide feature of FlowFields that let you see the underlying transactions that make up the information shown in the FlowField.

For text boxes, the default is the form defined in the DrillDownFormID property for the table

Expand image See Also

Concepts

Properties


DropDown Property

DropDown Property

Sets a drop-down menu for a text box. The drop-down menu shows the user a list of the available options.

Expand image Applies To

  • Forms

  • Pages

  • Text boxes

Expand image Property Value

Yes if a drop-down menu for the text box is provided; otherwise, No. The default value is No.

Expand image Remarks

For option fields, define the drop-down list options using the OptionString Property.

Expand image See Also

Reference

OptionString Property


Editable Property

Editable Property

Sets a value that indicates whether a field, form, or control can be edited.

Expand image Applies To

  • Check boxes

  • Fields

  • Forms

  • Frames

  • Matrix boxes

  • Menu items

  • Option buttons

  • Pages

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Yes if the field, form, or control can be edited; otherwise, No. The default value is Yes.

Expand image Remarks

For fields, use this property to make a field for display only.

For controls, if the Editable setting for the container that contains this control is set to No, that setting overrides what you enter here.

If a form has Editable set to a value of No, then the controls on the form are not editable, even if the (individual) Editable properties are set to Yes.

This property can be set dynamically by using the UPDATEEDITABLE Function (Control, Form) in the OnBeforeInput Trigger of the control.

Expand image See Also

Reference

UPDATEEDITABLE Function (Control, Form)
OnBeforeInput Trigger


Ellipsis Property

Ellipsis Property

Sets a value that specifies whether an ellipsis (...) is appended to the caption on a command button or menu item. An ellipsis tells the user that other choices will appear if he selects the command button or menu item.

Expand image Applies To

  • Command buttons

  • Forms

  • Menu items

  • Pages

Expand image Property Value

Yes if the ellipsis is appended; otherwise, No. The default value is No.

Expand image See Also

Concepts

Properties


Enabled Property

Enabled Property

Sets a value that indicates whether a field or key is activated or deactivated, or whether a control can respond to user-generated events.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Fields

  • Forms

  • Frames

  • Indicators

  • Keys

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Pages

  • Picture boxes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Yes if the field, key, or control is enabled; otherwise, No. The default value is Yes.

Expand image Remarks

For keys, this property determines whether a key is maintained in the database. If you are not using the key or if you seldom use the key, you may want to mark it as disabled for performance reasons. When you need to use the key you can change this setting.

For fields, this property determines whether you can store data in the field. If the field is unused, disable it to conserve database space. In a dataport, a disabled field is read from the external file on import, but it is not inserted in the database.

For controls, the Enabled setting for the container that contains this control overrides what is entered here.

Menu items, buttons, and labels for text boxes are automatically grayed when they are disabled.

For controls, this property can be set dynamically by using the EDITABLE Function (Control, Form).

Expand image See Also

Reference

EDITABLE Function (Control, Form)


EnabledIfError Property

EnabledIfError Property

Sets a value that specifies whether an action is enabled or disabled if it enters an error state.

Expand image Applies To

  • Actions

  • Pages

Expand image Property Value

Yes/No

Expand image See Also

Reference

EnabledIfInsertion Property
EnabledIfSelection Property


EnabledIfInsertion Property

EnabledIfInsertion Property

Sets a value that indicates whether the action should be enabled or disabled if the record is undefined.

Expand image Applies To

  • Actions

  • Pages

Expand image Property Value

Yes/No

Expand image See Also

Reference

EnabledIfError Property
EnabledIfSelection Property


EnabledIfSelection Property

EnabledIfSelection Property

Sets a value that indicates whether the selected action is enabled or disabled.

Expand image Applies To

  • Actions

  • Pages

Expand image Property Value

Yes/No

Expand image See Also

Reference

EnabledIfError Property
EnabledIfInsertion Property


EnableExternalAssemblies Property

EnableExternalAssemblies Property

Sets whether external Microsoft .NET assemblies can be used on a report.

Expand image Applies To

Client report definition (RDLC) report layouts

Expand image Property Value

Yes if external assemblies can be used; otherwise, No. The default is No.

Expand image Remarks

When you use the Visual Studio Report Designer for creating reports for the RoleTailored client, you can reference external assemblies to add functionality to a report. The location of the assembly must be accessible from the RoleTailored client. To use external assemblies on a report, the EnableExternalAssemblies property must be set to Yes.

For more information about referencing assemblies, see Adding Custom Code to a Report (Visual Studio Report Designer).

Expand image Security Considerations

Microsoft Dynamics NAV 2009 cannot verify assemblies and protect against malicious sources that may be harmful to your computer. You should set the EnableExternalAssemblies property to Yes only if you can ensure that assemblies on the report come from a trusted source.

Expand image See Also

Concepts

Properties
Designing Reports for the RoleTailored Client
Redesigning Classic Reports with Visual Studio Report Designer


EnableExternalImages Property

EnableExternalImages Property

Sets whether external images are allowed on a report.

Expand image Applies To

Client report definition (RDLC) report layouts

Expand image Property Value

Yes if external images are allowed; otherwise, No. The default is No.

Expand image Remarks

When you use the Visual Studio Report Designer for creating reports for the RoleTailored client, you can add images such as your company logo to a report. You can add either embedded or external images.

  • With an embedded image, the source file is compiled as part of the report. If a report only uses embedded images, then you can set the EnableExternalImages property to No. For an example of using embedded images, see How to add a Company Picture to a Report.

  • With an external image, the source file is stored outside of the report in a location that must be accessible from the RoleTailored client, such as on a file server or local computer. The image is referenced from the report and loads when the report opens. To use external images on a report, the EnableExternalImages property must be set to Yes.

    Note Note

    The EnableExternalImages property exposes the LocalReport.EnableExternalImages property of the Microsoft.ReportViewer.WebForms.LocalReport object, which is embedded in Microsoft Dynamics NAV 2009. The Microsoft.ReportViewer.WebForms.LocalReport object is part of the ReportViewer controls that are available in Visual Studio for adding reports to your application.

For information about adding images using Visual Studio Report Designer, see Adding Images to a Report (Visual Studio Report Designer).

Expand image Security Considerations

Microsoft Dynamics NAV 2009 cannot verify image sources and protect against malicious images or sources that may be harmful to your computer. You should set the EnableExternalImages property to Yes only if you can ensure that images on the report come from a trusted source.

Expand image See Also

Concepts

Properties
Designing Reports for the RoleTailored Client
Redesigning Classic Reports with Visual Studio Report Designer


EnableHyperlinks Property

EnableHyperlinks Property

Sets whether hyperlinks to URLs are allowed on reports.

Expand image Applies To

Client report definition (RDLC) report layouts

Expand image Property Value

Yes if links to other URLs from the report are allowed; otherwise, No. The default is No.

Expand image Remarks

When you use the Visual Studio Report Designer for creating reports for the RoleTailored client, you can add hyperlinks on controls that target different URLs. This allows you set up a link from a field on a report to another report or page of the RoleTailored client for drilling down into data. To use hyperlinks on a report, the EnableHyperlinks property must be set to Yes. For examples that use this property, see Walkthrough: Creating a Link from a Report to a Report and Walkthrough: Creating a Link from a Report to a Page.

Note Note

The EnableHyperlinks property exposes the LocalReport.EnableHyperlinks Property of the Microsoft.ReportViewer.WebForms.LocalReport object, which is embedded in Microsoft Dynamics NAV 2009. The Microsoft.ReportViewer.WebForms.LocalReport object is part of the ReportViewer controls that are available in Visual Studio for adding reports to your application.

Expand image Security Considerations

Microsoft Dynamics NAV 2009 cannot verify URLs and protect against malicious sites that may be harmful to your computer. You should set the EnableHyperlinks property to Yes only if you can ensure that hyperlinks on the report target trusted sites.

Expand image See Also

Concepts

Properties
Designing Reports for the RoleTailored Client
Redesigning Classic Reports with Visual Studio Report Designer


Encoding Property

Encoding Property

Sets a value that specifies which system is applied to the XMLport for character encoding.

Expand image Applies To

XMLports

Expand image Remarks

The two options available for this property are UTF8 and UTF16. UTF8 is the default setting. Information about the encoding system used is inserted into the header of the XML document. For example, <? XML version = 1.0 encoding=utf8 ?>.

Expand image See Also

Concepts

Properties


ExtendedDataType Property

ExtendedDataType Property

Sets the extended data type of a control.

Expand image Applies To

  • Pages

  • Subtype - Field

  • Type - Control

Expand image Remarks

The value of this property overrides the value of the table field and it converts a text field into one of the following:

  • None

  • Phone number

  • E-mail address

  • URL

  • Filter (used on Reports)

  • Ratio (to monitor the progress bar)

  • Masked

This property impacts the layout and behavior of controls on a page. Use it to add an icon next to an input field to denote whether the field relates to a phone number, e-mail address, or URL. This property applies validation to the field.

Expand image See Also

Concepts

Properties


Field No. Property

Field No. Property

Sets a unique numeric ID for the field.

Expand image Applies To

Fields

Expand image Remarks

No two fields can have the same Field No. within a table. The Field No. is used for reference purposes and you can use the Name Property in code. The Name is automatically converted to the Field No. when C/AL code is compiled.

Usually, the Field No. is automatically assigned by Table Designer when you add fields to a table.

Expand image See Also

Reference

Name Property


FieldClass Property

FieldClass Property

Sets the class of the field.

Expand image Applies To

Fields

Expand image Property Value

Value | Description
Normal | A data entry field
FlowFilter | To compute the results of FlowFields
FlowField | A calculated field

Expand image Remarks

There are three classes of fields: Normal, FlowFields, and FlowFilters.

Expand image See Also

Concepts

Properties


FieldEndDelimiter Property

FieldEndDelimiter Property

Sets the string that is to be used to mark the end of a field.

Expand image Applies To

Dataports

Expand image Property Value

Value | Description
<None> | There is no FieldEndDelimiter
<NewLine> | Any combination of CR and LF characters
<CR/LF> | CR followed by LF
<CR> | CR alone
<LF> | LF alone
<TAB> | Tabulator alone
Other strings | The literal string entered

Expand image Remarks

The strings in the preceding table must be entered literally, using the < and > characters. These special strings can be combined, and can also be mixed with other characters.

The default is value is a quote (<">).

CR refers to the character with ASCII value 13.

LF refers to the character with ASCII value 10.

FieldEndDelimiter is only used if FileFormat Property is set to Variable. Otherwise, the setting is ignored.

The string defined as FieldEndDelimiter is used in addition to the string defined as FieldSeparator Property. The intended use is when the fields include characters that are themselves delimiters. If it is not necessary to use FieldEndDelimiter for this purpose, set it to a value of <None>.

When importing, the delimiters can be present in the file. The following example shows what would happen if FieldStartDelimiter and FieldEndDelimiter are equal to " and FieldSeparator is equal to ,.

a,"b",c,"text with comma,",d

The result would be broken into fields like this:

a

b

c

text with comma,

d

Expand image See Also

Reference

FieldStartDelimiter Property


FieldSeparator Property

FieldSeparator Property

Sets the string that is to be used to separate fields.

Expand image Applies To

  • Dataports

  • XMLports

Expand image Property Value

Value | Description
<None> | There is no field separator
<NewLine> | Any combination of CR and LF characters
<CR/LF> | CR followed by LF
<CR> | CR alone
<LF> | LF alone
<TAB> | Tabulator alone
Other strings | The literal string entered

Expand image Remarks

The strings in the preceding table must be entered literally, using the < and > characters. These special strings can be combined and can also be mixed with other characters.

The default value is a comma (<,>).

CR refers to the character with ASCII value 13.

LF refers to the character with ASCII value 10.

FieldSeparator is only used if the FileFormat Property is set to Variable. Otherwise, the setting is ignored.

Expand image See Also

Reference

FieldEndDelimiter Property
FieldStartDelimiter Property


FieldStartDelimiter Property

FieldStartDelimiter Property

Sets the string that is to be used to mark the start of a field.

Expand image Applies To

Dataports

Expand image Property Value

Value | Description
<None> | There is no FieldStartDelimiter
<NewLine> | Any combination of CR and LF characters
<CR/LF> | CR followed by LF
<CR> | CR alone
<LF> | LF alone
<TAB> | Tabulator alone
Other strings | The literal string entered

Expand image Remarks

The strings in the preceding table must be entered literally, using the < and > characters. These special strings can be combined, and also be mixed with other characters.

The default is " (a quote).

CR refers to the character with ASCII value 13.

LF refers to the character with ASCII value 10.

FieldStartDelimiter is only used if the FileFormat Property is Variable. Otherwise, the setting is ignored.

The string defined as FieldStartDelimiter is used in addition to the string defined as the FieldSeparator Property. Use this in situations where the fields include characters that are themselves delimiters. If it is not necessary to use FieldStartDelimiter for this purpose, set it to a value of <None>.

When importing, the delimiters can be present in the file. The following example shows what would happen if FieldStartDelimiter and FieldEndDelimiter are equal to " and FieldSeparator is equal to ,.

a,"b",c,"text with comma,",d

The result would be broken into fields like this:

a

b

c

text with comma,

d

Expand image See Also

Reference

FieldEndDelimiter Property


FieldValidate Property

FieldValidate Property

Sets a value that specifies whether the values in the source field are validated by the OnValidate (Fields) Trigger trigger for the field.

Expand image Applies To

XMLports

Expand image Property Value

Yes if the fields are validated; otherwise, No. The default value is Undefined.

Expand image Remarks

This property only applies to fields and works in combination with the DefaultFieldsValidation Property XMLport property.

The DefaultFieldsValidation property sets the value for the FieldValidate XMLport field property. Therefore, if you change the setting of the DefaultFieldsValidation property, the change is implemented for all fields. However, if the FieldValidate property of a field is set to Yes or No, no change will be made to this field.

If you change the value of the FieldValidate property, the change does not affect the value of the DefaultFieldsValidation property. This means that FieldValidate can override DefaultFieldsValidation, but that it can also inherit the default value of DefaultFieldsValidation.

Expand image See Also

Reference

DefaultFieldsValidation Property
OnValidate (Fields) Trigger


FileFormat Property

FileFormat Property

Sets the format of the file that a dataport reads from or writes to.

Expand image Applies To

Dataports

Expand image Property Value

Value | Description
Variable (default) | Read/write in a variable length format
Fixed | Read/write in a fixed length format

Expand image Remarks

If FileFormat is set to Variable, you must also set the FieldEndDelimiter Property, FieldStartDelimiter Property and FieldSeparator Property to define how fields are separated.

If FileFormat is set to Fixed, these properties are ignored, and the StartPos Property and Width Property must be set to define the placement of the fields in the imported line.

Expand image See Also

Reference

FieldEndDelimiter Property
FieldStartDelimiter Property
FieldSeparator Property
StartPos Property
Width Property


FileName Property

FileName Property

Sets the name of the external file to read data from or write data to a dataport or XMLport.

Expand image Applies To

  • Dataports

  • XMLports

Expand image Remarks

The FileName property must be set to a valid file name or a run-time error occurs.

This property can be set dynamically by using the FILENAME Function (Dataport, XMLport). Using this function with the Import Property function, you can create dataports or XMLports that are dynamic, meaning that they can determine whether data is input or output at run time, and the name of the external file to read from or write to can also be set at run time.

If FileName is blank, a default request options form tab will be created, where this property can be set at run time. If no name is specified or the UseReqForm Property property is set to No, then a run-time error occurs.

Expand image See Also

Reference

FILENAME Function (Dataport, XMLport)
UseReqForm Property
Import Property


Focusable Property

Focusable Property

Sets a value that specifies whether a control can gain focus.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Indicators

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Picture boxes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Yes if the control can receive focus; otherwise, No. The default value is Yes.

Expand image Remarks

If the Focusable setting for the container that contains this control is set to No, that setting overrides what you enter here.

Expand image See Also

Reference

FocusOnClick Property
Cancel Property


FocusOnClick Property

FocusOnClick Property

Sets a value that allows the user to put focus on the control by clicking the mouse or by using the designated access key.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Menu buttons

  • Option buttons

Expand image Property Value

Yes if the user places focus on this control by clicking or using the access key; otherwise, No. The default value is Yes for check boxes and option buttons. The default value is No for command buttons and menu buttons.

Expand image Remarks

For example, if you create a form that lists sales orders and you added a command button that enabled users to post all selected orders, set the command button's FocusOnClick property to a value of No. Otherwise, when the user clicked the command button, focus would be removed from the selected orders, and there would be nothing to post.

With the exception of command buttons, menu buttons, check boxes, and option buttons, focusable controls always receive focus when you click on them.

Expand image See Also

Reference

Focusable Property


FontBold Property

FontBold Property

Sets a value that indicates whether to display text in boldface.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Labels

  • Menu buttons

  • Option buttons

  • Tab controls

  • Text boxes

Expand image Property Value

Yes if the text is displayed in boldface; otherwise, No. The default value is No.

Expand image Remarks

For text boxes, the setting of this property can be changed dynamically by using the UPDATEFONTBOLD Function (Control) in the OnFormat Trigger trigger.

Expand image See Also

Reference

FontSize Property
FontName Property
FontItalic Property
FontStrikethru Property
FontUnderline Property


FontItalic Property

FontItalic Property

Sets a value that specifies whether text is italicized.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Labels

  • Menu buttons

  • Option buttons

  • Pages

  • Tab controls

Expand image Property Value

Yes if the text is displayed in italics; otherwise, No. The default value is No.

Expand image See Also

Reference

FontSize Property
FontBold Property
FontName Property
FontStrikethru Property
FontUnderline Property


FontName Property

FontName Property

Sets the name of the font that is displayed.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Labels

  • Menu buttons

  • Option buttons

  • Tab controls

Expand image Remarks

FontName is a string that contains the name of the typeface you want to use. The default font is MS Sans Serif.

Expand image See Also

Reference

FontSize Property
FontBold Property
FontItalic Property
FontStrikethru Property
FontUnderline Property


FontSize Property

FontSize Property

Sets the point size of the font that is displayed.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Labels

  • Menu buttons

  • Option buttons

  • Tab controls

Expand image Remarks

FontSize is an integer that specifies the font size in points. The default font size is 8pt.

Expand image See Also

Reference

FontName Property
FontBold Property
FontItalic Property
FontStrikethru Property
FontUnderline Property


FontStrikethru Property

FontStrikethru Property

Sets a value that specifies whether text is displayed in strikeout.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Labels

  • Menu buttons

  • Option buttons

  • Pages

  • Tab controls

Expand image Property Value

Yes if the text is displayed with strikeout; otherwise, No. The default value is No.

Expand image See Also

Reference

FontSize Property
FontBold Property
FontItalic Property
FontName Property
FontUnderline Property


FontUnderline Property

FontUnderline Property

Sets a value that specifies whether text is underlined.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Labels

  • Menu buttons

  • Option buttons

  • Pages

  • Tab controls

Expand image Property Value

Yes if the text is displayed with an underline; otherwise, No. The default value is No.

Expand image See Also

Reference

FontSize Property
FontBold Property
FontItalic Property
FontName Property
FontStrikethru Property


ForeColor Property

ForeColor Property

Sets the foreground color of the control.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Indicators

  • Labels

  • Menu buttons

  • Option boxes

  • Tab controls

  • Text boxes

Expand image Remarks

Use the Color option on the View menu to pick a color or enter the RGB Color Model value of a color for the foreground. The default value is the system foreground color.

Expand image See Also

Reference

BackColor Property
BackTransparent Property


Format Property

Format Property

Sets the formats of the source expression for various data types.

Expand image Applies To

  • Dataport fields

  • Text boxes

  • XMLports

Expand image Remarks

You can set the Format property to a predefined format, or you can build your own format. For more information, see FORMAT Function (Code, Text).

Basic Settings

To choose a predefined format, use the syntax: <Standard Format,X>, where X is one of the entries in the Value column of the following table.

Value | Description
0 | Standard Display Format (the default for all data types)
1 | Standard Display Format 2 (edit)
2 | C/AL Code Constant Format
Note Note

You must enter the < and > angle brackets, such as <Standard Format,2>.

Building Formats

You can use the Format property to create your own formats. To create a format, use the following rules:

  • A format property consists of zero or more Chars, Fields, or Attributes.

  • Fields and Attributes are expressed with an identifier inside brackets (<>).

  • Attributes must contain a comma (,) and a parameter after the identifier.

  • Fields can optionally take a comma (,) and a FieldLen.

The following table shows the syntax.

FormatProperty := | [<Char> | <Field> | <Attribute>]
<Char> := | character with ASCII value [32..255]
<Field> := | '<' <FieldName> [',' <FieldLen>] '>' [, <Attribute>]
<FieldName> := | literal name of field (format component)
<FieldLen> := | length of field (0 or no entry means that the length is dynamic)
<Attribute> := | ['<' <AttributeName> ',' <Char> '>']
<AttributeName> := | [Standard Format | Filler | 1000Character | Comma | Overflow | Filler Character | Precision]
Note Note

In the following table, a full stop is used as the decimal symbol. Filler and Filler Character indicate the character that is used to fill empty spaces.

The FieldName is a component that you can use to build a format expression. Depending on the data type of the text box or dataport field, you can choose the appropriate FieldName from this list.

Data type | FieldName values
Decimal | Sign, Integer, Decimals, Integer Thousand
Date | Day, Month, Month Text, Quarter, Year, Year4, Week, Week Year, Week Year4, Weekday, Weekday Text, Closing
Time | Hours24, Hours12, Minutes, Seconds, Thousands, AM/PM, Second dec
DateTime | Day, Month, Month Text, Quarter, Year, Year4, Week, Week Year, Week Year4, Weekday, Weekday Text, Hours24, Hours12, Minutes, Seconds, Thousands, AM/PM, Second dec
Integer, BigInteger | Sign, Integer, Integer Thousand
Boolean | Text, Number
Option | Text, Number
Code | Text
Char | Char/Number, Char, Number
Text | Text

Example

The following examples demonstrate how to use the Format property:

  • Choosing a standard format.

    Use the Standard Format attribute to select one of the standard formats (these are listed at the end of this Help topic).

    For example, <Standard Format,5> selects Standard Format 5.

  • Using a standard format with an attribute.

    <Precision,2:3><Standard Format,0> will use Standard Format 0 and will format the data with a minimum of 2 and a maximum of 3 decimal places. See also the DecimalPlaces Property. If you do not specify a precision, then the form uses the precision that is specified in the DecimalPlaces Property of the corresponding field in the table.

  • Building a format.

    You can create your own formats using Chars (which are displayed literally), Fields (to choose specific components of a value, for example the year-part of a date) and Attributes (for example to select which character to use as a filler).

    For example, a text box that is based on a source expression of the Date data type can use the following format string:

    <Weekday Text>, <Month Text> <Day>

    This expression displays the date as Monday, April 15.

    Note Note

    The settings that are specified under the Regional and Language Options in Windows determine how some separators are displayed.

Standard Formats

The following tables list the predefined formats for each data type.

Decimal Format Example

<Sign><Integer Thousand><Decimals>

0

-76,543.21

<Sign><Integer><Decimals>

1

-76543.21

<Sign><Integer><Decimals>

Note Note

The difference between format 1 and 2 is that format 2 always uses a period (.) as the decimal separator, regardless of the Regional setting.

2

-76543.21

<Integer Thousand><Decimals><Sign,1>

3

76,543.21-

<Integer><Decimals><Sign,1>

4

76543.21-

XML format

9

-76543.21

For Dates, the Regional and Language Options in Windows is used to select the actual format that is used. The following table shows the fields that are used to build the various formats. This table corresponds to the Regional setting for a European country/region.

Date | Format | Example
<Closing><Day,2>-<Month,2>-<Year> | 0 | 05-04-03
<Closing><Day,2>-<Month,2>-<Year> | 1 | 05-04-03
<Day,2><Month,2><Year><Closing>D | 2 | 050403D
<Closing><Year>-<Month,2>-<Day,2> | 3 | 03-04-05
<Closing><Day>. <Month Text> <Year4> | 4 | 5. April 2003
<Closing><Day,2><Month,2><Year> | 5 | 050403
<Closing><Year><Month,2><Day,2> | 6 | 030405
<Day,2><Filler Character, >. <Month Text,3> <Year4> | 7 | 5. Apr 2003
XML format | 9 | 2003-04-05

The following table shows how these formats will change if the Regional and Language Options is set to "United States."

US date | Format | Example
<Closing><Month,2>/<Day,2>/<Year> | 0 | 04/05/03
<Closing><Month,2>/<Day,2>/<Year> | 1 | 04/05/03
<Month,2><Day,2><Year><Closing>D | 2 | 040503D
<Closing><Year>/<Month,2>/<Day,2> | 3 | 03/04/05
<Month Text> <Closing><Day>, <Year4> | 4 | April 5, 2003
<Closing><Month,2><Day,2><Year> | 5 | 040503
<Closing><Year><Month,2><Day,2> | 6 | 030405
<Day,2><Filler Character, >. <Month Text,3> <Year4> | 7 | 5. Apr 2003
XML format | 9 | 2003-04-05

For Times, the Regional and Language Options in Windows are used to select the actual format used. The following table shows the fields that will be used to build the various formats. This table corresponds to the Regional setting for a European country/region.

Time | Format | Example
<Hours24>.<Minutes,2>.<Seconds,2> | 0 | 4.35.55
<Hours24>.<Minutes,2>.<Seconds,2><Second dec.> | 1 | 4.35.55.553
<Hours24,2><Filler Character,0><Minutes,2><Seconds,2> <Second dec.><Comma,.>T | 2 | 043555.553T
XML format | 9 | 04.35.55.553Z

The following table shows how these time formats will appear if the Regional setting is changed to "United States."

US time | Format | Example
<Hours12>:<Minutes,2>:<Seconds,2><Second dec.> <AM/PM> | 0 | 4:35:55 AM
<Hours12>:<Minutes,2>:<Seconds,2><Second dec.> <AM/PM> | 1 | 4:35:55.553 AM
<Hours24,2><Filler Character,0><Minutes,2><Seconds,2> <Second dec.><Comma,.>T | 2 | 043555 .553T
XML format | 9 | 04:35:55.553Z

The following table shows the fields that have been used to define the standard formats for DateTime. Note that the date, time, and decimal separators that are displayed are determined by the Regional and Language Options that have been selected on your computer.

DateTime | Format | Example
<Day,2>-<Month,2>-<Year> <Hours24>.<Minutes,2> | 0 | 05-04-03 4.35
<Day,2>-<Month,2>-<Year> <Hours24>.<Minutes,2>.<Seconds,2><Second dec> | 1 | 05-04-03 4.35.55.553
<Day,2>-<Month,2>-<Year> <Hours24>.<Minutes,2> | 2 | 05-04-03 4.35
<Day,2>-<Month,2>-<Year> <Hours24>.<Minutes,2>.<Seconds,2> | 3 | 05-04-03 4.35.55
XML format | 9 | 2003-04-05T03:35:55.553Z
US DateTime | Format | Example
<Month,2>/<Day,2>/<Year> <Hours24,2>:<Minutes,2> <AM/PM> | 0 | 04/05/03 04:35 AM
<Month,2>/<Day,2>/<Year> <Hours24,2>:<Minutes,2>:<Seconds,2><Second dec> <AM/PM> | 1 | 04/05/03 04:35:55.553 AM
<Month,2>/<Day,2>/<Year> <Hours24,2>:<Minutes,2> <AM/PM> | 2 | 04/05/03 04:35 AM
<Month,2>/<Day,2>/<Year> <Hours24,2>:<Minutes,2>:<Seconds,2> <AM/PM> | 3 | 04/05/03 04:35:55 AM
XML format | 9 | 2003-04-05T03:35:55.553Z
Integer and BigInteger | Format | Example
<Sign><Integer> | 0 | -567
<Sign><Integer> | 1 | -567
<Sign><Integer> | 2 | -567
XML format | 9 | -567
Boolean | Format | Example
<Text> | 0 | Yes/No
<Text> | 1 | Yes/No
<Number> | 2 | 1/0
XML format | 9 | true/false
Option | Format | Example
<Text> | 0 | Blue
<Text> | 1 | Blue
<Number> | 2 | 1
XML format | 9 | 1

Standard format 9 is used to display the data in the standard XML formats.

For Chars, all formats are: <Char/Number>.

For Text and Code, all formats are: <Text>.

Expand image See Also

Reference

DecimalPlaces Property


Format/Evaluate Property

Format/Evaluate Property

Sets the data that is being imported or exported as XML data types or as the standard C/SIDE data types.

Expand image Applies To

XMLports

Expand image Property Values

C/SIDE Format/Evaluate (default)

XML Format/Evaluate

Expand image Remarks

Importing

If the XML document that you want to import contains data that corresponds to the standard C/SIDE data types, use C/SIDE Format/Evaluate (default value). The data is then evaluated before being inserted into the database.

If the XML document that you want to import contains data that uses the standard XML data types, use the XML Format/Evaluate setting. This ensures that the data is evaluated and converted to the C/SIDE data types before being inserted into the database.

If the data that you want to import does not follow either the Standard C/SIDE formats or the XML formats, import the data into a temporary table in text format. You can then use C/AL code to convert the data before inserting it into the database.

Exporting

If you want to export data that uses the standard C/SIDE data types to an XML document and use these data types in the XML document, use C/SIDE Format/Evaluate (default value). The data from the database is then formatted according to the standard rules for C/SIDE data types.

If you want to export data in the standard XML formats to an XML document, use the XML Format/Evaluate setting. This ensures that the data you export from the database is formatted and exported in the standard XML formats.

The following XML Data types require evaluation.

XML Data Type | Microsoft Dynamics NAV Data Type
Decimal Float Double | Decimal
Boolean | Boolean
Datetime | DateTime
Time | Time
Date | Date
Integer | Integer
Duration | Duration

This is an XMLport property and therefore applies to all the data that is being streamed. It cannot be applied only to specific fields.

For more information about formatting C/SIDE data types, see Format Property. For more information about evaluating variables, see EVALUATE Function. For more information about using temporary tables, see Temporary (XMLports) Property.

Expand image See Also

Reference

Format Property
EVALUATE Function
Temporary (XMLports) Property


FreezeColumnID Property

FreezeColumnID Property

Sets a value that freezes the last column in a repeater control.

Expand image Applies To

  • Pages

Expand image Remarks

This is the last column to be frozen in the repeater control. All columns before this will also be frozen.


FunctionType Property

FunctionType Property

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Sets the type of function in a test codeunit.

Expand image Applies To

C/AL functions on test codeunits. A test codeunit is codeunit that has the SubType Property (Codeunit) set to Test.

Note Note

The FunctionType property is only visible when the Show C/AL Testability properties option of the Classic client is set to Yes. To change this setting, on the Tools menu, click Options.

Expand image Property Value

Value | Description
Normal | Acts as normal function.
Test | Tests the application.
MessageHandler | Handles MESSAGE functions.
ConfirmHandler | Handles CONFIRM functions.
StrMenuHandler | Handles STRMENU functions.
FormHandler | Handles specific forms that are not run modally.
ModalFormHandler | Handles specific forms that are run modally.
ReportHandler | Handles specific reports.

Expand image Remarks

You create test codeunits to test your application. A test codeunit can consist of one or more test functions, handler functions, and normal functions.

  • You use test functions that include C/AL code that performs a test on an area of the application. For more information, see How to: Create Test Codeunits and Test Functions.

  • You use handler functions to automate tests by handling instances when user interaction is required by the code that is being tested by the test function. In these instances, the handler function is run instead of the requested user interface. The handler function should simulate the user interaction for the test case, such as validating messages, making selections, or entering values. For example, a test function that has a FunctionType of MessageHandler handles MESSAGE function calls. If the code that is being tested calls the MESSAGE function, then the MessageHandler function that is declared for that test function is called instead of the MESSAGE function. You write code in the MessageHandler function to verify that the expected message is displayed by the MESSAGE function.

    Note Note

    The parameters of the functions that are being handled are passed as parameters to the handler functions. The value of the parameter can be changed by the handler function.

    To set up handler function for use by a test function, you assign the handler function to the HandlerFunctions Property of the test function.

    For more information, see How to: Create Handler Functions

  • You use normal functions to structure the test code by using the same design practices and principles as functions in other codeunits of the application.

Expand image See Also

Tasks

How to: Create Test Codeunits and Test Functions
How to: Create Handler Functions
Walkthrough: Testing Vendor Discount

Concepts

Testing the Application


GroupType Property

GroupType Property

Sets the GroupType property in Page Designer when you want to add one of the following controls to a page:

  • Container

  • Group

  • Field

  • Part

Expand image Applies To

  • Pages

Expand image Remarks

When you select GroupType in Page Designer you can also choose from one of the following subtypes:

  • Group

  • Repeater

  • CueGroup

  • FixedLayout - Arranges fields in rows and columns. For more information, see Arranging Fields in Rows and Columns Using a FixedLayout Control and How to: Arrange Page Fields in Rows and Columns Using a FixedLayout Control.

Expand image See Also

Concepts

Arranging Fields in Rows and Columns Using a FixedLayout Control


GroupTotalFields Property

GroupTotalFields Property

Sets data item fields used to group records.

Expand image Applies To

Data items on Classic report layouts

Expand image Remarks

The GroupTotalFields is used with the TotalFields Property to maintain totals for one or more fields. Both group totals and the grand totals can be output by using the appropriate sections. Enter this property value as a comma-separated list of field names. The fields can be selected by using the AssistEdit button from the Value field of the property. Fields in the list must also be fields in the active key of the underlying table. If not, the report displaying the data items will not run.

When records are retrieved, they are grouped by the contents of the fields that are defined by the GroupTotalFields property. If more than one field is provided in the list, the groups are nested. This means that there is a group composed of records that have the same contents in the first field indicated. Inside of this group, records are grouped according to the contents of the second field in the list, and so on.

The GroupHeader section is output before a new group is started. The GroupFooter section is output after all records in a group are processed. The fields designated as TotalFields Property contain group totals for the last processed group. The group totals are printed by placing controls that have these fields as their source expressions in the GroupFooter section.

The TOTALSCAUSEDBY Function (Report) can be used to determine which field has changed contents, and thus which group is finished. Using this function is necessary if you define more than one field in GroupTotalFields and need to decide whether to output a GroupHeader or GroupFooter section.

When using the GroupTotalFields property, be aware of the relationship to the currently active key in the underlying table. Because the GroupTotalFields functionality is closely connected with the active key, some precautions might be required. For example, the No. and City fields are listed as GroupTotalFields while the active key consists of the No., Name, and City fields. If the contents of the Name field change as the records are processed, any grouping based on the City field will fail. Therefore, it may be necessary to prevent the user from choosing a key from the request form of the report, because the grouping only works with the one key that it was designed for. You can remove the request form by using the UseReqForm Property, or remove the Sort button by using the DataItemTableView Property property to set an explicit sorting order (key) for the data item.

Expand image See Also

Reference

TotalFields Property
TOTALSCAUSEDBY Function (Report)
UseReqForm Property
DataItemTableView Property


HandlerFunctions Property

HandlerFunctions Property

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Specifies the handler functions that are used by the test function.

Expand image Applies To

C/AL test functions on test codeunits. A test function is a function that has the FunctionType Property set to Test.

Note Note

The HandlerFunctions property is only visible when the Show C/AL Testability properties option of the Classic client is set to Yes. To change this setting, on the Tools menu, click Options.

Expand image Property Value

The handler function name as specified on the Functions tab of the C/AL Global window for the test codeunit.

Note Note

If the test function uses more than one handler function, then you should separate the handler function names by a comma.

Expand image Remarks

You use test codeunits and test functions to test your application. A handler function allows you to automate tests by handling instances when user interaction is required by the code that is being tested. In these instances, the test function calls the handler function, which is run instead of the user interface.

The following is some important information about handler functions:

  • To be a handler function, the FunctionType Property must set to one of the handler types: MessageHandler, ConfirmHandler, StrMenuHandler, FormHandler, ModalFormHandler, ReportHandler.

  • A test function can only call handler functions that are defined in the same test codeunit as the test function.

  • A test function can call MessageHandler, ConfirmHandler and StrMenuHandler type handlers only once. It can call FormHandler, ModalFormHandler, and ReportHandler type handlers multiple times but only once per application object ID.

  • Every handler function that you enter in the HandlerFunctions property must be called at least once in the test function. If you execute a test function that has a handler function listed that is not called, then the test fails.

For more information, see Testing the Application and How to: Create Handler Functions.

Expand image See Also

Tasks

How to: Create Test Codeunits and Test Functions
How to: Create Handler Functions
Walkthrough: Testing Vendor Discount

Concepts

Testing the Application


HeadingHeight Property

HeadingHeight Property

Sets the height of the column headings in a table or matrix box.

Expand image Applies To

  • Matrix boxes

  • Table boxes

Expand image Remarks

Enter zero (0) if you do not want a heading.

Specify the height in increments of 1/100 millimeter.

Expand image See Also

Concepts

Properties


Height Property

Height Property

Sets the height of the control or form. The height is displayed in increments of 1/100 of a millimeter.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

You can either select the form or control and then use the mouse to size it or enter an exact measurement using this property.

Changing the height of a form does not affect any subforms. You can change the setting of this property dynamically by using the HEIGHT Function (Control, Form) function.

For controls, this property setting is ignored for any control that is contained within a table box.

The Height property is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

Width Property
HorzGrid Property
VertGrid Property


HideValue Property

HideValue Property

Sets whether to show or hide a value for the user based on an expression.

Expand image Applies To

Pages

Expand image Property Values

True if the value is hidden; otherwise, False. The default is False.

Expand image See Also

Concepts

Properties


HorzAlign Property

HorzAlign Property

Sets how data or the control caption are horizontally aligned.

Expand image Applies to

  • Check boxes

  • Command buttons

  • Labels

  • Menu buttons

  • Option buttons

  • Text boxes

Expand image Property Value

Value | Description
Left | Align data on the left
Right | Align data on the right
Center | Align data in the center
General (default) | Align data to the right if numeric, otherwise to the left

Expand image Remarks

If you choose values of Right or Center, the rightmost part of the text is truncated, as required.

This property is not supported in the RoleTailored client.

Expand image See Also

Reference

VertAlign Property


HorzGlue Property

HorzGlue Property

Sets a value that specifies how to anchor the control horizontally.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Value | Description
Left (default) | Anchor the control on the left
Right | Anchor the control on the right
Both | Anchor the control on the left and right

Expand image Remarks

If this control is contained in a table box, the setting for this control is ignored.

If the control is used as a column in a table box and you set the HorzGlue property to a value of Both, the column will resize accordingly when the user resizes the frame.

If you set this property to a value of Both for several columns in a table box, the settings will apply to the leftmost column.

With the exception of the HorzGlue property on columns, the HorzGlue property and VertGlue Property are typically not active at design time.

This property is not supported in the RoleTailored client.

Expand image See Also

Reference

VertGlue Property


HorzGrid Property

HorzGrid Property

Set the distance between horizontal grid lines in the form and section designers.

Expand image Applies To

  • Forms

  • Classic report layouts (sections)

Expand image Property Value

Value | Description
Default (1.1 millimeter) | To use the default setting
Zero or infinite | To display no horizontal grid
A number; 0 means no grid | To display a custom grid you define

Expand image Remarks

The grid is shown as one dot per five grid distances. The unit of measure is 1/100 mm. Enter zero (0) or infinite if you do not want to display a horizontal grid.

Expand image See Also

Reference

VertGrid Property


ID Property

ID Property

Sets a unique numeric ID for this codeunit, table, page, form, report, dataport, XMLport, or control.

Expand image Applies To

  • Check boxes

  • Codeunits

  • Command buttons

  • Dataports

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Pages

  • Picture boxes

  • Reports

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Tables

  • Text boxes

  • XMLports

Expand image Remarks

The ID must be unique within the scope of the object. For example, two code units, tables, or forms cannot have the same ID, and no control can have the same ID as another control on that form.

The ID is used for reference purposes. As a result, you can use the value of the Name Property to reference objects in your code. The Name is automatically converted to the ID when the code is compiled.

If you do not set the ID property, you will be prompted for one when you save the object. For controls, a numeric ID is assigned based on the next available number for the form or the report. You can change this ID.

Expand image See Also

Reference

Name Property


Image Property

Image Property

Specifies the image that you want to associate with an action object. You can only choose from the available default images. There are different images that you can use on actions in the action pane and activity buttons. For more information, see Action Image Library and Activity Button Image Library.

Note Note

The image property is not valid on page link actions that are set up under activity buttons in the navigation pane. These actions use a default image that cannot be changed.

Expand image Applies To

  • Action and ActionGroup controls on pages

Expand image See Also

Tasks

How to: Add Actions to the Action Pane on Pages
How to: Add Images to the Action Pane by Using Transformation Input
How to: Add an Image to an Activity Button
How to: Set an Image on an Action

Concepts

Properties


Import Property

Import Property

Use this property to determine whether the dataport imports or exports data.

Expand image Applies To

Dataports

Expand image Property Value

Value | Description
Yes (default) | Import data to a C/SIDE table
No | Export data to an external file

Expand image Remarks

This property can be set dynamically by using the IMPORT Function (Dataport). Using this function in combination with the FileName Property, you can create dynamics dataports. Dynamics dataports are those for which it can be determined at runtime whether data should be input or output, and the name of the external file to read from or write to can be set.

Import can only be set dynamically in the OnPreDataPort Trigger.

If Import is blank, a default request options form tab is created, allowing this property to be set at runtime.

Expand image See Also

Reference

IMPORT Function (Dataport)
FileName Property
OnPreDataPort Trigger


Importance Property

Importance Property

Sets the amount of information that is visible in a window or dialog box.

Expand image Applies To

Pages

Expand image Remarks

Different parts of a dialog box or window can be hidden by setting this property. The available options are:

  • Standard (typically visible)

  • Promoted (always visible)

  • Additional (hidden by default)

You can set the Importance property if you are an administrator or as a user personalization option.

Expand image See Also

Concepts

Properties


IncludeInDataSet Property

IncludeInDataSet Property

Sets whether the C/AL variable's value is included in the dataset of the RoleTailored client.

Expand image Applies To

C/AL variables of Boolean Data Type or Integer Data Type on pages.

Expand image Property Value

Yes to include the variable's value in the dataset; otherwise, No. The default is No.

Expand image Remarks

You must set this property to Yes if the variable is used as the value of the Editable Property, Enabled Property, Visible Property, or StyleExpr Property.

Expand image See Also

Tasks

How to: Style Field Text on a Page


InColumn Property

InColumn Property

Use this property when the parent is a data container and control fills a column.

Expand image Applies To

  • Check boxes

  • Indicators

  • Option buttons

  • Picture boxes

  • Text boxes

Expand image Remarks

There is no default setting for this property. Usually, this property is set for you when you create a data control inside a table box.

Expand image See Also

Reference

InColumnHeading Property


InColumnHeading Property

InColumnHeading Property

Use this property when the parent is a data container, when the InColumn Property is set to Yes, and the control fills the heading of the column.

Expand image Applies To

  • Images

  • Labels

  • Shapes

Expand image Remarks

There is no default setting. Usually, this property is set for you when you create a static control inside a table box.

Expand image See Also

Reference

InColumn Property


Indent Property

Indent Property

Sets the value by which to indent text from the left margin.

Expand image Applies To

Text boxes

Expand image Remarks

You can only set indention from the OnFormat Trigger trigger by using the UPDATEINDENT Function (Text Box) function. The unit of measure is 1/100 mm.

Expand image See Also

Reference

OnFormat Trigger
UPDATEINDENT Function (Text Box)


Indentation Property

Indentation Property

Sets the indentation level of an element or an attribute in XMLport Designer.

Expand image Applies To

XMLports

Expand image Remarks

In XMLport Designer, specify the names of elements and their attributes in the Tag Name field.

When you are determining the indentation level of an element or an attribute, remember the following:

  • List the elements and their attributes in the order that they appear in the XML document.

  • List child elements and attributes under the parent element that they define.

  • Only indent each child one level more than its parent.

  • Only the first element can have an indentation of 0.

  • The indentation level that you set in the Properties window corresponds directly to the indentation level you can set in XMLport Designer. You can also use the buttons in XMLport Designer to change the indentation level of an element or an attribute.

Expand image See Also

Concepts

Properties


IndentationColumnName Property

IndentationColumnName Property

Sets the name of the hidden column that controls row indentation in a List page.

Expand image Applies To

  • Pages (Type = Group, Subtype = Repeater)

Expand image Remarks

This property can be set to a field or variable of Integer Data Type. For an example of row indentation, see the Chart of Accounts.

Expand image See Also

Reference

IndentationControls Property


IndentationControls Property

IndentationControls Property

Sets the value by which columns (controls) are indented.

Expand image Applies To

  • Pages

  • Type - Group

  • Subtype – Repeater

Expand image Remarks

To access the Indent Controls window select a Group container in Page Designer and then view properties. The Indentation Controls property allows you to choose which columns are indented below a group control on a List page. Click the Assistbutton to open the Indent Controls window. In the Indent Controls window you can see all the field controls that are below a Group container on a List page.

Define which columns you want to indent by placing a check mark next to the appropriate field control in the Indentation column. Click OK and the selected fields appear as comma-separated values in the Value column.

Expand image See Also

Reference

IndentationColumnName Property


InFooterBar Property

InFooterBar Property

Sets whether an action should be viewed as an exit action in the lower part of the page.

Expand image Applies To

  • Actions

  • Pages

Expand image Remarks

Available options:

Yes/No (Boolean)

Expand image See Also

Concepts

Properties


InFrame Property

InFrame Property

Use this property when the parent is a frame and the control is located inside the frame.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

There is no default setting. Usually, the property is set for you when you create a control inside a frame.

Expand image See Also

Concepts

Properties


InitValue Property

InitValue Property

Sets the initial value of this field when a user creates a new record.

Expand image Applies To

Fields

Expand image Remarks

This attribute is only important if you create the record in a window or by using the C/AL functions InitValue Property, CLEAR Function, or CLEARALL Function. For example, this attribute is commonly used in Boolean fields when you want either Yes or No to be the default.

Expand image See Also

Reference

InitValue Property
CLEAR Function
CLEARALL Function


InlineEditing Property

InlineEditing Property

Sets a value that specifies whether users are required to click in the table box or press F2 to begin editing the text inside the table box.

Expand image Applies To

  • Matrix boxes

  • Table boxes

Expand image Property Value

No if you want the user to be able to edit a form without clicking or pressing F2; otherwise, Yes. The default value is No.

Expand image Remarks

If this property is set to Yes, no editing is allowed when the form is opened. The user must click an active editable control, press F2 when an editable control is in focus, or choose to insert a new record to begin editing.

The setting of this property can be changed dynamically by using the INLINEEDITING Function (Matrix Box,Table Box).

This property is not supported in the RoleTailored client.

Expand image See Also

Reference

INLINEEDITING Function (Matrix Box,Table Box)


InMatrix Property

InMatrix Property

Use this property when the parent is a matrix box and the control fills the matrix part of a matrix box.

Expand image Applies To

  • Check boxes

  • Indicators

  • Option buttons

  • Picture boxes

  • Text boxes

Expand image Remarks

There is no default setting for this property. Usually, this property is set for you when you create a data control inside a matrix box.

Expand image See Also

Reference

InMatrixHeading Property


InMatrixHeading Property

InMatrixHeading Property

Use this property to place the control in the heading of the matrix when the parent is a matrix box and InMatrix Property is set to Yes

Expand image Applies To

  • Images

  • Labels

  • Shapes

Expand image Remarks

There is no default setting.

Usually, this property is for you when you create a static control inside a matrix box.

Expand image See Also

Reference

InMatrix Property


InPage Property

InPage Property

Use this property when the parent property is a tab control and you want to specify the page the control appears on.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

There is no default setting. Usually, this property is set for you when you create a control inside a tab control.

Expand image See Also

Reference

PageNames Property


InsertAllowed Property

InsertAllowed Property

Sets a value to specify whether users can add records while using the form or page.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if you want to allow users to add records; otherwise, No. The default value is Yes.

Expand image See Also

Concepts

Properties


InstructionalTextML Property

InstructionalTextML Property

Sets the multilanguage value of the InstructionalText of the object. Use this property as a label.

Expand image Applies To

Pages

Expand image See Also

Concepts

Properties


InvalidActionAppearance Property

InvalidActionAppearance Property

Sets how to display the caption and, if applicable, the bitmap, if the action that you specified using PushAction Property could not be performed.

Expand image Applies To

  • Command buttons

  • Menu items

Expand image Property Value

Value | Description
Normal | Keep the same appearance
Disable (default) | Gray the caption and bitmap
Hide | Hide the caption and bitmap

Expand image Remarks

This property is evaluated when a form or menu is opened.

Expand image See Also

Reference

PushAction Property


KeepWithNext Property

KeepWithNext Property

Sets value that specifies whether to disallow page breaks between two sections of the same type.

Expand image Applies To

Sections

Expand image Property Value

Yes if you want to disallow page breaks between the sections; otherwise, No. The default value is Yes.

Expand image See Also

Concepts

Properties


Key Property

Key Property

Use this property to identify the field or fields that make up this key.

Expand image Applies To

Keys

Expand image Remarks

You can select up to 20 fields for each key and you can have up to 40 keys for each table. The combination of the data in the fields that you select for the key must be unique. The first key that you create is the primary key for the table. If the key consists of more than one field, separate the fields with commas. For more information, see Table Keys.

Searching for specific data is usually easier if several keys are defined and maintained for the table. The indexes for each of the keys provide specific views that let the system quickly perform flexible searches. There are advantages and disadvantages to creating a large number of keys. For examples, see the following table.

Value | Performance increases | Performance slows
Increase the number of secondary keys marked as active | When you retrieve data in several different sorting sequences, because the data is already sorted. | When you enter data because indexes need to be maintained for each secondary key.
Decrease the number of secondary keys marked as active | When you enter data because there are fewer indexes to maintain. | When you retrieve data. You may have to define or reactivate the secondary keys to get the appropriate sorting. Depending on the size of the database, this can take some time, because the index must be rebuilt.

Expand image See Also

Concepts

Table Keys


KeyGroups Property

KeyGroups Property

Sets the predefined key groups to which a key belongs.

Expand image Applies To

Keys

Expand image Remarks

After you have assigned a key to one or more key groups, you can selectively activate or deactivate the key by enabling and disabling the key groups.

Adding a large number of keys to a database table decreases performance. However, by making the keys members of predefined key groups you can have the necessary keys defined and only activate them when they are going to be used, thus improving performance.

To enable or disable a key group for sorting, do the following:

  1. Click File, click Database, and then click Information to open the Database Information window.

  2. Click Tables, and then click Key Groups. The Database Key Groups window opens.

  3. Enable or disable a key group by clicking the appropriate button.

It is difficult to get an overview of the keys and tables that are affected when you enable or disable a key group. To see which keys in a table belong to a key group, do the following:

  1. Open a table in Table Designer, and click View, and then click Keys to open the Keys window. You can now see the keys that have been defined for that table.

  2. With the focus on the Keys window, click View, and then click Show Column to open the Show Column window.

  3. In the Show Column window, click KeyGroups, and then click OK.

The Keys window now displays a KeyGroups column that lists the key groups that any of the keys in this table belong to.

To enable or disable a key, open the Keys window for the appropriate table and click or clear the Enabled field next to the key.

Expand image See Also

Reference

KEYGROUPDISABLE Function
KEYGROUPENABLE Function
KEYGROUPENABLED Function


LeaderDots Property

LeaderDots Property

Sets a series of leading characters (…) before or after the data.

Expand image Applies To

  • Labels

  • Text boxes

Expand image Property Value

Yes if you want to display leading dots; otherwise, No. The default value is Yes for labels unless in a column heading, and No for textboxes.

Expand image Remarks

If you enter a value of Yes, the setting for the PadChar Property is ignored.

The leading characters are placed before, after, or both before and after the caption when the HorzAlign Property is set to a value of Right, Left, or Center, respectively.

Expand image See Also

Reference

PadChar Property
HorzAlign Property


LeftMargin Property

LeftMargin Property

Sets the left margin of a report. The unit of measure is 1/100 mm.

Expand image Applies To

Reports

Expand image Remarks

A left margin specified in the page setup dialog overrides the value of LeftMargin.

Some printers require a minimum margin. If you specify a margin that is less than the minimum margin, the minimum margin is used when printing.

The default value is 21 mm.

The LeftMargin property is not supported on client report definition (RDLC) report layouts. The create layout suggestion function sets the margin values on RDLC report layouts.

Expand image See Also

Concepts

Properties


LinkedInTransaction Property

LinkedInTransaction Property

Gets and sets data from linked server data sources, such as Microsoft Office Excel, Access, or another SQL Server.

Expand image Applies To

Microsoft Dynamics NAV with Microsoft SQL Server.

Expand image Remarks

This property is available when the LinkedObject Property property is set to Yes.

Set the LinkedInTransaction property to No when the Microsoft Dynamics NAV table description refers to an object outside of the current database or on a linked server.

The access to linked server data sources is not under Microsoft Dynamics NAV transaction control. This means that if a Microsoft Dynamics NAV transaction is aborted, any changes that were made to a linked object that is outside the current database or on a linked server during this transaction will remain in effect.

Expand image See Also

Reference

LinkedObject Property


LinkedObject Property

LinkedObject Property

Use this property to link to SQL Server objects.

Expand image Applies To

Tables

Expand image Remarks

When you set the LinkedObject property to Yes, the LinkedInTransaction Property property becomes available.

Expand image See Also

Reference

Table Properties


LinkFields Property

LinkFields Property

Specifies the fields that are linked between two tables using the LinkTable Property. This property is only available for XML items that have a table as their data source.

Expand image Applies To

XMLports

Expand image Property Value

Value | Description
<field> | A field from the table that is specified as the data source of this XML item
<reference field> | A field from the table that is specified in the LinkTable Property.

Expand image Remarks

The following syntax shows the LinkFields property.

CopyCode image Copy Code
<field>=FIELD(<reference field>)

This property works in combination with the LinkTable Property and the LinkTableForceInsert Property.

The property sets a filter on the table that is the data source for the XML item. The filter selects only those records that contain the same <field> value in source table as the <reference field> value from the table specified in LinkTable Property.

For example, you have defined two XML items—one based on the Customer table that contains a list of customers and one based on the Sales Header table that contains a record of each sales order that has been made.

In the Customer table, the primary key is the customer number and is stored in the No. field. In the Sales Header table that contains the sales data, each record contains this customer number as a foreign key in the field called Sell-to Customer No.

Setting the LinkTable Property of the second XML item to point to the Customer table and setting the Linkfields property of the first XML item to point to the Sell-to Customer No. field places a filter on the records in the Customer table. This means that only those records in the Sales Header table that refer to the current customer are selected.

The same result can be obtained by placing this C/AL statement in the OnPreXMLItem Trigger of the child data item.

CopyCode image Copy Code
SETRANGE("Sell-to Customer No.",Customer."No.");

Expand image See Also

Reference

LinkTable Property
LinkTableForceInsert Property


LinksAllowed Property

LinksAllowed Property

Sets whether links are allowed.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if links are allowed; otherwise, No. The default value is Yes.

Expand image Remarks

If LinksAllowed is Yes, then you can add links or notes to a form or page. The links can be a links to Web sites, files stored on the local computer or on a remote computer, or links to forms or pages.

On a page, the links and notes are displayed in FactBoxes. If LinksAllowed is Yes, then the Actions menu has a Notes item and a Links item. You use these to create and modify notes and links.


LinkTable Property

LinkTable Property

Sets the table that this XML item should be linked to. This property is only available for XML items that have a table as their data source.

Expand image Applies To

XMLports

Expand image Remarks

This property works in combination with the LinkFields Property and the LinkTableForceInsert Property.

Exporting

In this example, you are exporting data about specific customers and the orders that they placed. You create an XMLport based on the following database tables:

  • A Customer table that contains general information about the customer, such as address, telephone number, and so on.

  • A Sales Header table that contains information about the orders placed by these customers.

In the Customer table, the primary key is the customer number and is stored in the No. field. In the Sales Header table, each record contains this customer number as a foreign key in the Sell-to Customer No field.

Set the LinkTable property of the Sales Header XML item to point to the Customer table and set the LinkFields Property of the Sales Header XML item so that the Sell-to Customer No. field is equal to the No. field in the Customer table. This places a filter on the records in the Customer table and ensures that only those records in the Sales Header table that refer to the customers you specified are selected and exported by the XMLport.

This corresponds to placing the following C/AL code in the OnPreXMLItem Trigger of the indented data item.

CopyCode image Copy Code
SETRANGE("Sell-to Customer No.",Customer."No.");

Importing

In this example, you are importing XML data that contains information about new customers as well as details about their first orders. You create an XMLport based on the following database tables:

  • A Customer table that contains general information about the customer, such as address, telephone and so on.

  • A Sales Header table that contains information about the orders placed by these customers.

In the Customer table, the primary key is the customer number and is stored in the No. field. In the Sales Header table, each record contains this customer number as a foreign key in the field called Sell-to Customer No.

You must set the LinkTable property of the Sales Header XML item to point to the Customer table and set the LinkFields Property of the Sales Header XML item so that the Sell-to Customer No. field points to the No. field in the Customer table. This ensures that the customer numbers in the incoming data stream are inserted into both the Customer table and the Sales Header table. The incoming data stream must conform to the XML schema that you have defined for your XMLport.

In this example, the information you are importing has a header/line relationship—each customer can place many orders. The customer information is the parent of the of the sales header information. In this kind of relationship the parent information generally functions as a kind of wrapper that encapsulates the information about the children.

The schema typically starts by supplying some of the parent information, followed by the information about the children, and it finishes by supplying the last of the parent information.

When the XML stream is processed, it begins with the parent information, for example, the customer number is inserted into the No. field in the Customer table. Next comes the sales header information and the customer number is inserted into the Sell-to Customer No. field in the Sales Header table. The rest of the sales header information is then inserted into that table.

In this case, you must use the LinkTableForceInsert Property to ensure that the parent information is inserted before the child information. The customer information is inserted into the Customer table before you start processing the sales header information. This makes it possible to validate the sales header information against the customer information as it is inserted.

After the sales header information has been processed, the last of the customer information is inserted into the Customer table.

If the customer number already exists, you will receive an error. This means that you will probably have to insert the data into a temporary table, modify it, and then insert it into the correct tables.

Expand image See Also

Concepts

Properties


LinkTableForceInsert Property

LinkTableForceInsert Property

Sets whether data from the linked table is forcibly inserted into a table to prevent an error from being generated.

Expand image Applies To

XMLports

Expand image Property Value

Yes if you want to forcibly insert data; otherwise, No. The default is Yes.

Expand image Remarks

This property works in combination with the LinkFields Property and the LinkTable Property.

Setting this property to Yes will forcibly insert data from the linked table and run the OnAfterInitRecord Trigger on the main table.

This feature is useful if you have a header to line relationship in your XML document. The table and the header information must be inserted before you can insert the line information. As a result, you can use this property to ensure that the header information is inserted before the XMLport starts reading the line information.

Expand image See Also

Reference

LinkFields Property
LinkTable Property


LogHeight Property

LogHeight Property

Sets the logical height of the form. The logical size of a form can be larger than its physical size, which is displayed when the form is opened. The unit of measure is 1/100 mm.

Expand image Applies To

Forms

Expand image Remarks

If the logical size of the form is set to be larger than the physical size, scroll bars are automatically added as needed. All controls are placed according to the logical size of the form. This means that controls can be scrolled out of view.

If you set this property to infinite, scroll bars are not included. You can change this property at runtime by using the LOGHEIGHT Function (Form).

The LogHeight property is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

LogWidth Property


LogWidth Property

LogWidth Property

Sets the logical width of the form. The logical size of the form can be larger than the physical size of the form, which is displayed when the form is opened. The unit of measure is 1/100 mm.

Expand image Applies To

Forms

Expand image Remarks

If the logical size of the form is set to be larger than the physical size, scroll bars are automatically added as needed. All controls are placed according to the logical size of the form. This means that controls can be scrolled out of view.

If you set this property to infinite, scroll bars will not be included. You can change this property at runtime by using the LOGWIDTH Function (Form).

The LogWidth property is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

LogHeight Property


Lookup Property

Lookup Property

Use this property to provide a lookup window for a text box.

Expand image Applies To

  • Forms

  • Pages

  • Text boxes

Expand image Property Value

Yes if you want a lookup for the text box; otherwise, No. The default value is No.

Expand image Remarks

By default, a lookup provides a list of records in the table. Using this list, users can select a record and retrieve information from it into this control. If you want the lookup to provide other functionality, use the OnLookup (Controls) Trigger to add C/AL code that provides that functionality.

Expand image See Also

Reference

LookupFormID Property
PermanentAssist Property


LookupFormID Property

LookupFormID Property

Sets the ID of the form you want to use as a lookup.

Expand image Applies To

  • Forms

  • Pages

  • Tables

  • Text boxes

Expand image Remarks

For text boxes, this value is set to the LookupFormID property value set for the table.

For tables, the default value LookUpFormID property is <Undefined>. By changing this value, you can determine which form is displayed when users press F6 (Lookup). For example, the LookupFormID property on the Customer table (18) is set to the Customer List form.

Expand image See Also

Reference

Lookup Property


LookupMode Property

LookupMode Property

Sets a value that indicates whether the form is in lookup mode.

Expand image Applies To

Forms

Expand image Property Value

Yes if you want this property to be in lookup mode; otherwise, No. The default is No.

Expand image Remarks

If you set LookupMode to No, the LookupOK and LookupCancel actions are disabled. The property is checked the form opens. The setting of this property can be changed dynamically by using the LOOKUPMODE Function (Form).

Expand image See Also

Reference

LOOKUPMODE Function (Form)


MaintainSIFTIndex Property

MaintainSIFTIndex Property

Sets the value to determine whether SIFT structures should be created in SQL Server to support the corresponding SumIndexFields for the Microsoft Dynamics NAV key.

Expand image Applies To

Keys

Expand image Property Value

Yes to create the SIFT structures in SQL Server; otherwise, No. The default is Yes.

Expand image Remarks

SumIndexFields are created in Microsoft Dynamics NAV to support FlowField calculations and other fast summing operations. SQL Server can sum numeric data by scanning the table. If the SIFT structures exist for the SumIndexFields, summing the fields is faster, especially for large sets of records, but modifications to the table are slower because the SIFT structures must also be maintained.

In situations where SumIndexFields must be created on a key to enable FlowField calculations, but the calculations are performed infrequently or on small sets of data, you can disable this property to prevent slow modifications to the table.

Expand image See Also

Concepts

Properties


MaintainSQLIndex Property

MaintainSQLIndex Property

Sets a value that indicates whether a SQL Server index that corresponds to the Microsoft Dynamics NAV key should be created.

Expand image Applies To

Keys

Expand image Property Value

Yes to create the SQL Server index; otherwise, No. The default is Yes.

Expand image Remarks

In Microsoft Dynamics NAV, you can use a key to sort data in a table by the set of fields specified in the key. SQL Server can sort data without an index on the fields to be sorted. However, if an index exists, sorting by the fields matching the index will be faster, but modifications to the table will be slower. The more indexes there are on a table, the slower the modifications become.

In situations where a key must be created to allow only occasional sorting (for example, when running infrequent reports), set this property to No to prevent slow modifications to the table.

Note Note

You cannot disable this property on the primary key of a table. This key is always created in SQL Server.

Expand image See Also

Concepts

Properties


MatrixColumnWidth Property

MatrixColumnWidth Property

Sets the width of the columns in a matrix box. The width is displayed in increments of 1/100 of a millimeter.

Expand image Applies To

Matrix boxes

Expand image Remarks

This property is updated when you use the mouse to resize columns. You can also enter an exact position manually in the Properties window.

Expand image See Also

Concepts

Properties


MatrixSourceTable Property

MatrixSourceTable Property

Sets the ID of the table to use as the matrix (horizontal) table of a matrix box.

Expand image Applies to

Matrix boxes

Expand image Remarks

Use the Lookup button to select the table that you want.

Expand image See Also

Concepts

Properties


Maximizable Property

Maximizable Property

Sets the value to determine whether the form should have a maximize button in the upper right corner.

Expand image Applies To

Forms

Expand image Property Value

Yes if you want to include a maximize button; otherwise, No. The default is Yes.

Expand image Remarks

This setting is checked when the form is opened. The Maximizable value does not impact any associated subforms.

Expand image See Also

Reference

Minimizable Property


MaximizedOnOpen Property

MaximizedOnOpen Property

Sets the value to determine whether the form is maximized when opened.

Expand image Applies To

Forms

Expand image Property Value

Yes if you want to maximize the form when opened; otherwise, No. The default is No.

Expand image Remarks

This property is evaluated when the form is opened; it does not impact associated subforms. You can set this property at runtime using C/AL code.

If the MinimizedOnOpen Property is set to No, then MaximizedOnOpen must be set to Yes.

This property is not supported on pages in the RoleTailored client.

Expand image See Also

Reference

MinimizedOnOpen Property


MaxIteration Property

MaxIteration Property

Sets a limit on the number of times that a data item will be iterated when the report is run.

Expand image Applies To

Data items

Expand image Remarks

Valid settings of this property are integers between 0 and the maximum value of an integer (2,147,483,647).

Expand image See Also

Concepts

Properties


MaxLength Property

MaxLength Property

Sets the maximum number of characters a user can enter into a text box.

Expand image Applies To

Text boxes

Expand image See Also

Reference

AutoEnter Property


MaxOccurs Property

MaxOccurs Property

Sets a value that indicates the maximum number of times an element can occur.

Expand image Applies To

XMLports

Expand image Property Value

SourceType | Default
Table | Unbounded
Text | Unbounded
Field | Once

Expand image Remarks

The default value of the MaxOccurs property varies depending on what you have selected as the SourceType Property of this element.

The minimum number of times an element can appear is determined by the value of the MinOccurs Property.

The MinOccurs and MaxOccurs properties conform to the standard occurrence constraints that are used when defining XML schemas.

The minimum number can be either 1 or 0.

The maximum number can be either 1 or infinite.

Expand image See Also

Concepts

Properties


MaxValue Property

MaxValue Property

Sets the maximum numeric value for a field or control.

Expand image Applies To

  • Check boxes

  • Fields

  • Forms

  • Indicators

  • Option boxes

  • Pages

  • Text boxes

Expand image Property Value

Value | Description
9999 | Integers
9999.0 | Decimals
December 31, 9999 | Dates
23:59:59 | Time

Expand image Remarks

For check boxes, option boxes, and text boxes, the default value of this property is taken from the value of the MaxValue property on the field. If there is no MaxValue setting on the field, then the default value is taken from the data type. You can set this property to a value more restrictive than the default value, but not less restrictive than the default value. For example, if the default value is 100, you can set this property to 99, but not to 101.

The control and field setting are checked during validation.

Expand image See Also

Reference

MinValue Property
NotBlank Property
Numeric Property


MenuItemType Property

MenuItemType Property

Sets the value for the type of menu item.

Expand image Applies To

Menu items

Expand image Property Value

Value | Description
MenuItem (default) | If the menu item is a standard menu item
Separator | If the menu item separates other items

Expand image Remarks

Specify the menu item properties using the menu item editor, which is available by selecting the Menu Items option on the View menu.

Expand image See Also

Concepts

Properties


MenuLevel Property

MenuLevel Property

Sets the menu level for a control. Levels are indicated by indentation.

Expand image Applies To

Menu items

Expand image Remarks

Usually you specify the menu item properties using the menu item editor, which you can display by selecting the Menu Items option on the View menu.

The number you enter indicates the relative level of the option. The default value is zero (0).

Expand image See Also

Concepts

Properties


MinOccurs Property

MinOccurs Property

Sets the minimum number of times that an element can occur.

Expand image Applies To

XMLports

Expand image Property Values

The possible values are Once and Zero (0). The default value is Once.

Expand image Remarks

The maximum number of times an element can appear is determined by the value of the MaxOccurs Property. The MinOccurs and MaxOccurs properties conform to the standard occurrence constraints that are used when defining XML schemas.

In the Classic client, the minimum number is 0. In the RoleTailored client, if you use Lazy API for XML (LAX), then the minimum number is 1. If you do not use LAX, then the minimum number is 0.

The maximum number can be either 1 or infinite.

Expand image See Also

Reference

MaxOccurs Property


Minimizable Property

Minimizable Property

Sets a value that indicates whether a minimize button is included in the upper right corner of the form.

Expand image Applies To

Forms

Expand image Property Values

Yes if the minimize button should be included; otherwise, No. The default value is Yes.

Expand image Remarks

This property is evaluated when the form is opened. This has no impact on associated subforms.

Expand image See Also

Concepts

Properties


MinimizedOnOpen Property

MinimizedOnOpen Property

Sets a value that determines whether the form is minimized on open.

Expand image Applies To

Forms

Expand image Property Value

Yes if you want to minimize the form when opened; otherwise, No. The default is No.

Expand image Remarks

This setting is checked when the form is opened. This has no impact on associated subforms.

You can only set MinimizedOnOpen to a value of Yes if the MaximizedOnOpen Property is set to a value of No.

This property can be set dynamically by using the MINIMIZEDONOPEN Function (Form).

This property is not supported on pages in the RoleTailored client.

Expand image See Also

Reference

MaximizedOnOpen Property


MinValue Property

MinValue Property

Sets the minimum value for a field or control.

Expand image Applies To

  • Check boxes

  • Fields

  • Forms

  • Indicators

  • Option boxes

  • Pages

  • Text boxes

Expand image Property Value

Value | Description
0 | Integers
0.0 | Decimals
January 1, 0 | Dates
00:00:00 | Time

Expand image Remarks

For check boxes, option boxes, and text boxes, the default value is taken from the field's MinValue setting. If there is no field MinValue setting, the default value is taken from the data type. You can set this property to a more restrictive value than the default, but you cannot set it to a less restrictive value. For example, if the default minimum value is 10, then you can set MinValue to 11, but not to 9.

Both the control and field setting are checked during validation.

Expand image See Also

Reference

MaxValue Property
NotBlank Property
Numeric Property


ModifyAllowed Property

ModifyAllowed Property

Sets the value to determine whether users can modify records while using this form.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if you want to allow the users to modify records; otherwise, No. The default is Yes.

Expand image See Also

Concepts

Properties


MultiLine Property

MultiLine Property

Sets the value that indicates whether a label or text box can display multiple lines of text inside a single text box or label.

Expand image Applies To

  • Forms

  • Labels

  • Pages

  • Text boxes

Expand image Property Value

Yes if you want if to display multiple lines when the control is a label used as a column heading; otherwise, No. The default is Yes.

Expand image See Also

Concepts

Properties


MultipleNewLines Property

MultipleNewLines Property

Sets a value that determines whether users can add multiple new lines between records.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if you want to allow users to add multiple new lines between records; otherwise, No. The default is No.

Expand image See Also

Reference

AutoSplitKey Property


Name Property

Name Property

Sets the name of the object. The name is used for internal identification of the object in C/AL code.

Expand image Applies To

  • Check boxes

  • Codeunits

  • Command buttons

  • Dataports

  • Fields

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Pages

  • Picture boxes

  • Reports

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Tables

  • Text boxes

  • XMLports

Expand image Remarks

Unlike the ID Property, the value of the Name property does not have to be unique; however, it is a good practice to use unique names. The Name can be up to 30 characters long.

When you use the Name in C/AL code, it is automatically converted to the value of the ID Property when the C/AL code is compiled.

For forms, reports, dataports, and XMLports, the name is the default for the Caption Property.

For controls, the default name is based on the ID for all controls except check boxes, option boxes, picture boxes, and indicators.

For option boxes, the default name is derived from the option value, the ID, or the variable or field name.

For check boxes, picture boxes, and indicators the default name comes from the ID, or the variable or field name.

Expand image See Also

Reference

ID Property
Caption Property


NewPagePerGroup Property

NewPagePerGroup Property

Sets the value that specifies whether a page break is generated before each new group defined by the GroupTotalFields Property.

Expand image Applies To

  • Data items on Classic report layouts

  • Settings on Classic report layouts

Expand image Property Value

Yes if you want to generate a page break; otherwise, No. The default is No.

Expand image Remarks

If you have specified more than one group in the GroupTotalFields Property, you may not want a page break generated for each group. In this case, use the TOTALSCAUSEDBY Function (Report) to find which group is changing and the NEWPAGE Function (Report) to generate page breaks as needed.

For more information about creating new pages on client report definition (RDLC) report layouts, see How to: Create New Pages per Record.

Expand image See Also

Reference

GroupTotalFields Property
TOTALSCAUSEDBY Function (Report)
NEWPAGE Function (Report)


NewPagePerRecord Property

NewPagePerRecord Property

Sets a value to determine whether a page break is generated after each record.

Expand image Applies To

Data items on Classic report layouts

Expand image Property Value

Yes if you want to generate a page break; otherwise, No. The default is No.

Expand image See Also

Tasks

How to: Create New Pages per Record

Concepts

Properties


NextControl Property

NextControl Property

Sets the control that has focus when the user leaves this control by pressing TAB or ENTER.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Indicators

  • Menu buttons

  • Option boxes

  • Picture boxes

  • Subforms

  • Text boxes

Expand image Remarks

On a card form, the movement is from top-to-bottom and left-to-right by default. On a tabular form, the movement is from left-to-right and top-to-bottom by default.

In a tab control, after the end of the page is reached, the tab is moved to the next page.

The NextControl property is not supported in the RoleTailored client in Microsoft Dynamics NAV 2009.

Expand image See Also

Reference

AutoEnter Property


NodeName Property

NodeName Property

Sets the name of a node in an XML document.

Expand image Applies To

XMLports

Expand image Remarks

The name that you specify is inserted in the NodeName field of the XMLport Designer of the element or attribute in question.

You must enter node names in the order that they appear in the XML document. Parent elements must precede their child elements. Indent the node names of child elements under their parent elements using one indentation per level. List attributes under the elements that they define and indent them to the child level.

Expand image See Also

Reference

NodeType Property


NodeType Property

NodeType Property

Sets the value to specify whether an XML object is an element or an attribute.

Expand image Applies To

XMLports

Expand image Remarks

The possible values are: Element and Attribute. The default value is Undefined.

This property is directly related to the NodeType field in the XMLport Designer.

Expand image See Also

Reference

NodeName Property


NotBlank Property

NotBlank Property

Sets a value that specifies whether users must enter a value in the selected field or text box.

Expand image Applies to

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Remarks

If you want to force the user to make an entry in this field before saving the record to the database, then use the OnBeforePutRecord Trigger.

You can use this property with the InitValue Property to ensure that an entry is made in this field. This setting is evaluated for controls and fields during validation.

You can set the NotBlank property to Yes on primary fields in a table. Do not set the NotBlank property to Yes on other fields in a table.

Expand image See Also

Reference

MinValue Property
MaxValue Property
Numeric Property


Numeric Property

Numeric Property

Sets a value that requires users to enter only numbers in the field or text box.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Remarks

This setting is checked for both the control and field during validation.

Expand image See Also

Reference

MinValue Property
MaxValue Property
NotBlank Property


Occurrence Property

Occurrence Property

Sets a value that specifies whether an attribute must occur in the data that is being imported or exported.

Expand image Applies To

XMLports

Expand image Property Value

Value | Description
Required (default) | If the attribute must be part of the data.
Optional | If the attribute does not have to be part of the data.

Expand image Remarks

This property is primarily used to ensure that the XML data that you are importing conforms to the data structure in Microsoft Dynamics NAV.

Expand image See Also

Concepts

Properties


OptionCaption Property

OptionCaption Property

Sets the text string options that are displayed to the user.

Expand image Remarks

OptionCaption sets the text used to show the option values available for a field, text box, or variable. The OptionString Property contains the set of values that are acceptable choices. If you have set the OptionCaptionML Property, this overrides the OptionCaption setting.

Expand image See Also

Reference

OptionString Property
OptionCaptionML Property


OptionCaptionML Property

OptionCaptionML Property

Sets the strings that are displayed to the user for selecting an option. OptionCaptionML is only used if the field, variable, or text box has an OptionString Property. The OptionString property contains the set of values that are acceptable choices, and it is one of these values that is saved in the database or used in C/AL code.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

  • Variables

Expand image Remarks

OptionCaptionML is multilanguage enabled so it can contain a list of text in different languages. The text that is displayed is selected according to the current language settings of the user. For more information, see Working with Multilanguage Functionality.

The OptionCaptionML property has the following format.

CopyCode image Copy Code
<Language ID>=<optioncaption [,optioncaption]*>

<Language ID> is a Windows standard three-letter language ID and <optioncaption [,optioncaption]*> is the OptionCaption text(s) for this language. Semicolons are used to separate entries.

Although you can use OptionCaptionML to limit the number of options displayed to the user, it is recommended that you use OptionString Property to do this. You cannot expand the set of options. If you do, a run-time error will occur when the user selects an option that is outside the option set defined for the field or variable.

The following is an example of an OptionCaptionML value.

CopyCode image Copy Code
DAN=Resultatopgørelse,Balance;DEU=GuV,Bilanz;ESP=Comercial,Balance

In this example, values are set up for Danish (DAN), German Standard (DEU), and Spanish Traditional Sort (ESP).

How to Enter OptionCaptionML Values

When you click the AssistEdit button in the OptionCaptionML Value field, the Multilanguage Editor opens. This editor is a form with two columns: Language and Value. The Language column is populated with all languages defined by Windows. For your convenience, the names, not the abbreviated names, of the languages are displayed. The OptionCaptionML value for a language is added by entering a value in the Value field for that language. You must close this form by clicking OK. If you close it by pressing the ESC key, the OptionCaptionML field is not updated.

Examples of Using OptionCaptionML

The following examples demonstrate the relationship between the OptionString Property and the OptionCaptionML property on fields (or variables) and controls.

  1. An Option field in a table has the following OptionString Property value: opt1,opt2,op3. The value of OptionCaptionML is not set. A form based on this table contains a text box that is based on the Option field. OptionString and OptionCaptionML are not set for the text box.

    Result Users see opt1, opt2, and opt3 as the available choices.

  2. An OptionCaptionML property is added to the database field containing DAN=valg1,valg2,valg3;ENG=choice1,choice2,choice3.

    Result If a user selects DAN as the language, valg1, valg2, valg3 will be the available choices on the form. If a user selects ENG, choice1, choice2, choice3 will be available. For more information about what happens when the selected language is not available, see Working with Multilanguage Functionality.

  3. An OptionCaptionML property is added to the text box containing DAN=valg nummer 1,valg nummer 2,valg nummer 3.

    Result If a user sets DAN as the language, the choices are valg nummer 1, valg nummer 2, valg nummer 3. If a user sets the language to ENG, the same set of choices are available.

  4. The OptionCaptionML is removed from the field. The OptionString Property is set on the field; the OptionCaptionML property on the text box is set to DAN. The text strings specified in the OptionCaptionML property are used for all languages.

    Result Same result as for example 3. As long as any OptionCaptionML property is set on the text box or the field, the OptionString Property is not used to display choices to the user.

Expand image See Also

Concepts

Working with Multilanguage Functionality


OptionString Property

OptionString Property

Sets the option values for a field, text box, or variable. OptionString is multilanguage enabled.

Expand image Subhead

  • Fields

  • Forms

  • Pages

  • Text boxes

  • Variables

Expand image Remarks

If the OptionCaptionML Property is set, then users see the OptionCaptionML values as the option values. However, the value that is used in C/AL code or that is stored in the database will be the corresponding value from the OptionString property.

This allows you to present strings to users in different languages. The strings that are displayed to users are selected according to the user's current language setting. For more information, see Working with Multilanguage Functionality. If the OptionCaptionML Property is not set, then users will see the values from OptionString.

For other multilanguage enabled properties (Caption Property, ToolTip Property, PageNames Property and ReqFilterHeading Property), there is a relationship between the property itself and the multilanguage counterpart. The only connection between the OptionString and OptionCaptionML properties is that if the OptionCaptionML property is not set, then the strings displayed are taken from the OptionString property.

For Option fields and variables, use this property to list the options you want to be accepted (and displayed, if OptionCaptionML is not set). You can enter a maximum of 250 characters. Separate the options with a comma. For example: option1,option2,option3.

For controls, you can use this property to limit the number of options that the user can select. You cannot add options; if you do, a run-time error occurs when users select an option outside the set of options defined for the field or variable.

This property setting is checked recursively during validation.

Expand image See Also

Reference

OptionCaptionML Property


OptionValue Property

OptionValue Property

Sets the value of this option button. When the SourceExpr Property of this option button matches the option value you enter here, the option button is highlighted.

Expand image Applies To

Option buttons

Expand image Remarks

Enter the value you want the current option to have.

Expand image See Also

Concepts

Properties


Orientation (Indicator) Property

Orientation (Indicator) Property

Sets the value to determine how a percentage indicator is filled. For example, you can use this property to display the status of a task that might take several minutes, such as printing a long report.

Expand image Applies To

Indicators

Expand image Property Value

Value | Description
Left (default) | If you want the indicator to fill from the left.
Right | If you want the indicator to fill from the right.
Top | If you want the indicator to fill from the top.
Bottom | If you want the indicator to fill from the bottom.

Expand image See Also

Concepts

Properties


Orientation (Report) Property

Orientation (Report) Property

Sets the page orientation for the report.

Expand image Applies To

Classic report layouts

Expand image Property Value

Value | Description
Portrait | Prints and previews the report in portrait mode.
Landscape | Prints and previews the report in landscape mode.

Expand image Remarks

Set Orientation to Undefined to have the default printer document settings determine the page orientation. Page orientation specified in the Page Setup dialog box overrides the value specified for the Orientation property.

Expand image See Also

Concepts

Properties


PadChar Property

PadChar Property

Sets a value that indicates which characters are used to pad a string.

Expand image Applies To

  • Labels

  • Text boxes

Expand image Remarks

Padchar is used in the HorzAlign Property to determine whether the characters should be added to the left, right, or both left and right (centered). Enter the character you want to use to pad the string. For example, if you want to pad the string with periods, enter a period (.).

Expand image See Also

Reference

LeaderDots Property


PageNames Property

PageNames Property

Sets a list of page names, separated by commas, which correspond to the pages of the tab control.

Expand image Applies To

Tab controls

Expand image Remarks

Use this property to specify the pages of a tab control. The value is taken from the PageNamesML Property if this property is set.

Expand image See Also

Reference

PageNamesML Property
ToolTipML Property
InPage Property


PageNamesML Property

PageNamesML Property

Sets text that is used as a caption for a page in a tab control.

Expand image Applies To

Tab controls

Expand image Remarks

The PageNamesML property is multilanguage enabled. This means that it can contain a list of text in different languages. The text that is displayed is selected according to the current language setting of the user. For more information, see Working with Multilanguage Functionality.

The PageNamesML property has the following format.

CopyCode image Copy Code
<Language ID>=<pagenames>

<Language ID> is a Windows standard three-letter language ID and <pagenames> is a list of page names as in the PageNames Property.

The following is an example PageNamesML value:

CopyCode image Copy Code
DAN=Generelt,Kommunikation,Fakturering;ENG=General,Communication,Invoicing

Values are set up for Danish (DAN) and UK English (ENG).

How to Enter PageNamesML Values

You can enter values for the PageNamesML property in two ways:

  • If you enter a PageNames Property value, this value is inserted in PageNamesML as the value for the language that is currently selected. If the language is set to Danish when a value is entered in PageNames, PageNamesML is updated with a DAN=<value> string. You have to use the abbreviated name (DAN for Danish, for example) of the languages.

  • When you click the AssistEdit button in the PageNamesML Value field, the Multilanguage Editor opens. This is a form with two columns: Language and Value. The Language column is populated with all languages defined by Windows. The PageNamesML value for a language is added by entering a value in the Value field for that language. You have to close this form by clicking OK. If it is closed by pressing the ESC key, the PageNamesML field is not updated.

Expand image See Also

Reference

PageNames Property

Concepts

Working with Multilanguage Functionality


PagePartID Property

PagePartID Property

Sets a link to another page.

Expand image Applies To

  • Pages

    • Subtype - UIPart

    • Type - Control

Expand image See Also

Reference

PartType Property
SystemPartID Property
ChartPartID Property


PageType Property

PageType Property

Sets the type of page that is created.

Expand image Applies To

Pages

Expand image Remarks

Use this property when you are creating new Pages. The value for the PageType property specifies how the Page is displayed in RoleTailored client. Valid options are as follows.

  • Card

  • List

  • RoleCenter

  • CardPart

  • ListPart

  • Document

  • Worksheet

  • ListPlus

  • ConfirmationDialog

  • NavigatePage

Expand image See Also

Concepts

Properties


PaperSize Property

PaperSize Property

Sets the paper size for a report.

Expand image Applies To

Classic report layouts

Expand image Remarks

Use the AssistButton to select a paper size from the list of paper sizes that are supported by a particular printer. The list of paper size names is taken from the fin.stx file.

If the printer that is used for this report does not support the specified PaperSize, the default document settings of the printer will determine the page size. You may also experience that the displayed name of a paper size is different in the page setup dialog. This is because the paper sizes that are displayed here are taken from the actual printer. The printer manufacturer may have given a paper size a different name than the one in the fin.stx file. The physical paper size, however, will be the same (if the actual printer supports this size).

Leave PaperSize as Undefined to have the default document settings of the printer that is used for this report determine the page size.

A paper size specified in the Page Setup dialog box overrides PaperSize.

If you want to use the custom page size associated with your printer driver, set the PaperSize property to Undefined. Specify the custom page size in your printer driver properties and use that as the default.

For more information about how to verify the paper size for a client report definition (RDLC) report layout, see How to: Verify the Paper Size.

Expand image See Also

Concepts

Properties


PaperSourceFirstPage Property

PaperSourceFirstPage Property

Sets value to determine which paper source to use when printing page one of the report.

Expand image Applies To

Classic report layouts

Expand image Remarks

Use the AssistButton to select a paper source from the list of paper sources supported by a particular printer. The list contains 13 standard trays and 8 printer specific trays. It is based on information in the fin.stx file.

If the printer that is used for this report does not support the specified PaperSourceFirstPage, it will use the default tray specified by the printer driver.

If you leave the PaperSourceFirstPage property as <Undefined>, the printer will use the default tray.

If you do not specify a value for the PaperSourceOtherPages Property, a value specified for PaperSourceFirstPage will apply.

The printer specific trays contained in the list are intended for use with printers that have other paper sources than the ones listed. To find out how a Printer Specific Feed is mapped to the actual feed on an actual printer, you will have to experiment with choosing a Printer Specific Feed. Then, when you select a printer in the Page Setup dialog box, you can see how the Printer Specific Feed is mapped for that particular printer.

A different setting in the Print or Page Setup dialog box overrides the value specified for the PaperSourceFirstPage property.

Expand image See Also

Reference

PAPERSOURCE Function (Report)


PaperSourceOtherPages Property

PaperSourceOtherPages Property

Sets the paper source to use when printing pages other than page one.

Expand image Applies To

Classic report layouts

Expand image Remarks

Use the AssistButton to select a paper source from the list of paper sources supported by a particular printer. The list contains 13 standard trays and 8 printer specific trays. It is based on information in the fin.stx file.

If the printer that is used for this report does not support the specified PaperSourceOtherPages, it will use the default tray specified by the printer driver.

If you leave the PaperSourceOtherPages property as <Undefined>, the printer will use the tray specified for the PaperSourceFirstPage Property. If you have not specified a value for this property, the printer will use the default tray.

The printer specific trays contained in the list are intended for use with printers that have other paper sources than the ones listed. To find out how a Printer Specific Feed is mapped to the actual feed on an actual printer, you will have to experiment with choosing a Printer Specific Feed. Then, when you select a printer in the Page Setup dialog box, you can see how the Printer Specific Feed is mapped for that particular printer.

Note Note

A different setting in the Print or Page Setup dialog boxes overrides the value specified for the PaperSourceOtherPages property.

Expand image See Also

Reference

PAPERSOURCE Function (Report)


ParentControl Property

ParentControl Property

Sets the parent control from which this control should inherit default attributes.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

Enter the ID of the control you want as the parent. There is no default setting.

Usually this property is set for you when you create a control inside a container control, when you create a label using the add label button of the ToolBox, or when you create controls from fields using the Field menu.

Expand image See Also

Concepts

Properties


PartType Property

PartType Property

Sets the type or part to display in a FactBox.

Expand image Applies To

  • Pages

    • Type - Control

    • Subtype - UIPart

Expand image Remarks

The available options are:

  • Page

  • System Part (For example, Outlook or Notes)

  • ChartType

Expand image See Also

Reference

PagePartID Property
SystemPartID Property
ChartPartID Property


PasswordText Property

PasswordText Property

Sets whether a string of asterisks (********) is displayed when a user enters text in the text box.

Expand image Applies To

Text boxes

Expand image Property Value

Yes if you want to display the asterisks; otherwise, No. The default is No.

Expand image See Also

Concepts

Properties


PasteIsValid Property

PasteIsValid Property

Sets whether inserting records into this table using the paste command is enabled.

Expand image Applies To

Tables

Expand image Property Value

Yes if you want to allow insert by pasting; otherwise, No. The default value is Yes.

Expand image Remarks

If records are usually inserted in the table through an external code unit function, set the PasteIsValid property equal to No.

The OnInsert Trigger of the table is executed when a record is inserted by pasting.

Expand image See Also

Reference

OnInsert Trigger


Percentage Property

Percentage Property

Sets whether an indicator that shows the user the completion percentage of the current task is displayed.

Expand image Applies To

Indicators

Expand image Property Value

Yes if you want display a percentage indicator; otherwise, No. The default is Yes.

Expand image Remarks

You can use a percentage indicator to tell the user the processing status of the lengthy tasks, such as the printing of a long report.

This property is not supported in the RoleTailored client.

Expand image See Also

Reference

Orientation (Indicator) Property


PermanentAssist Property

PermanentAssist Property

Sets whether the lookup, drill-down, AssistEdit Property, and drop-down buttons are always displayed.

Expand image Applies To

Text boxes

Expand image Property Value

Yes if you want to only display these buttons when the control is in focus; otherwise, No. The default is Yes.

Expand image Remarks

This property is ignored when the control is in a column in a table box.

Expand image See Also

Reference

Lookup Property
DrillDown Property
DropDown Property


Permissions Property

Permissions Property

Sets whether a database object has additional permission required to perform some operations on one or more tables. The operations can be to read, insert, modify, and delete data.

Expand image Applies To

  • Codeunits

  • Dataports

  • Forms

  • Pages

  • Reports

  • Tables

  • XMLports

Expand image Remarks

The license file determines the permissions that users have within Microsoft Dynamics NAV. These permissions are further refined by the security permissions that you grant the different users.

Sometimes the license file only gives you indirect permission to perform operations on certain tables. Security permissions can also be used to give users only indirect permission to certain tables. If you only have indirect permission to, for example, insert data into a particular table, you cannot insert data into this table from the standard user interface. You must use a database object that has been given extra permission to insert data into the table in question.

Note Note

After you set the Permissions property of an object, only users with direct permission to perform all the extra operations that the object has been given can modify this object.

Do not use the Permissions property to give extra permissions to an object that you would like your users to be able to modify. These users might not have direct permission to perform these operations. This is why you should be careful when you use the Permissions property for tables and forms.

Expand image See Also

Concepts

Properties


PlaceInBottom Property

PlaceInBottom Property

Sets whether a footer section should be printed at the bottom of the (physical) page.

Expand image Applies To

Footer sections

Expand image Property Value

Yes if you want to always print the section at the bottom of the page; otherwise, No. The default is No.

Expand image Remarks

This property has the greatest impact on the last page of a report, but there might also be white space at the bottom of other pages. This is the case if the next section to print does not fit in what remains of the physical page.

Expand image See Also

Concepts

Properties


PopulateAllFields Property

PopulateAllFields Property

Sets whether fields are filled out automatically with a single filter value when a new record is inserted in a table.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if you want the fields filled out automatically; otherwise, No. The default is No.

Expand image Remarks

Values are inserted in those fields where a currently active filter expression evaluates to exactly one value. Key fields are always populated.

Differences Between the Classic Client and RoleTailored Client

If you are running the Classic client and if identical filters are set on the same field in different filter groups, then the filter value is not populated into the field when initializing a new record. For example, a filter for Document Type = Order is set on a new sales order form by the RunFormLink property, which is filtergroup 0, and also by the SourceTableView property, which is filtergroup 2. When you create a new sales order form, the filter for value "Order" is not populated into the field "Document Type," even though the two filters are simple and identical. The two identical filters are considered a complex filter, and the value is not populated into the field when a new record is initialized.

If you are running the RoleTailored client, then the behavior is different. If the following conditions apply, then the filter value is populated into a field:

  • Simple, identical filters are set on the same field in different filter groups.

  • A new record is being populated.

The filter value is assigned to the field immediately before the OnNewRecord Trigger is executed.

For more information, see FILTERGROUP Function (Record).

Expand image See Also

Concepts

Properties


PreserveWhiteSpace Property

PreserveWhiteSpace Property

Determines whether white space should be preserved in documents that are imported through an XMLport.

By default, Microsoft Dynamics NAV supports the XML standard by normalizing white space in attribute names and values that are imported through an XMLport. It converts tabs, carriage returns, and spaces to single spaces. It also eliminates leading and trailing white space.

When this property is set to Yes, none of these normalizations is performed.

Expand image Applies To

XMLports

Expand image Property Value

No to normalize white space; Yes to not normalize white space. The default is No.

Expand image See Also

Concepts

Properties


PrintOnEveryPage Property

PrintOnEveryPage Property

Sets a value that indicates whether a header or footer section is printed on every page or only on the first (headers) or the last (footers).

Expand image Applies To

Header and footer sections

Expand image Property Value

Yes if you want to print on every page; otherwise, No. The default, printing on the first or last page only, is No.

Expand image See Also

Concepts

Properties


PrintOnlyIfDetail Property

PrintOnlyIfDetail Property

Sets whether the decision to output the sections of a data item are based on whether an indented data item—or several nested data items—generate any output.

Expand image Applies To

  • Data items

  • Settings

Expand image Property Value

Yes if you want print output only if indented data items produce output; otherwise, No. The default is No.

Expand image See Also

Concepts

Properties


ProcessingOnly Property

ProcessingOnly Property

Sets the value that indicates whether a report produces printed output or only processes data.

Expand image Applies To

  • Reports

  • Settings

Expand image Property Value

Yes if you want a report that will not produce output; otherwise, No. The default is No.

Expand image Remarks

You are not allowed to insert controls in any section when ProcessingOnly is Yes.

If ProcessingOnly is Yes, the Print and Preview options on the request form are replaced by an OK button.

Expand image See Also

Concepts

Properties


Promoted Property

Promoted Property

Sets the value that indicates whether the selected action is promoted to the Actions Pane.

Expand image Applies To

  • Pages, Action Designer

    • Type - Action

Expand image Remarks

This feature allows you to make a copy of an Action and place it on the Actions Pane so that it easier to find.

Available options are Yes/No (Boolean).

Expand image See Also

Tasks

How to: Add Actions to the Action Pane on Pages
How to: Promote Actions to the Action Pane By Using Transformation Input

Reference

PromotedIsBig Property


PromotedCategory Property

PromotedCategory Property

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Sets a category for a promoted action.

Expand image Applies To

  • Page actions

Expand image Remarks

Promoted actions appear in the Action Pane on a page. You promote an action by setting the Promoted Property. Categories allow you to group similar actions under a common caption. You can choose between 10 categories: New, Process, Report, and Category4 through Category10. By default, the category names are used as the captions in the Action Pane. For information about changing the captions, see How to: Define Promoted Action Categories Captions for the Action Pane.

Expand image See Also

Tasks

How to: Add Actions to the Action Pane on Pages

Concepts

Properties


PromotedIsBig Property

PromotedIsBig Property

Sets a value that indicates whether the promoted action is displayed on the Actions Pane with a large icon.

Expand image Applies to

  • Pages, Action Designer

    • Type - Action

Expand image Remarks

Available options are Yes/No (Boolean).

Expand image See Also

Tasks

How to: Add Actions to the Action Pane on Pages
How to: Promote Actions to the Action Pane By Using Transformation Input

Reference

Promoted Property


ProviderID Property

ProviderID Property

Sets the ProviderID for a FactBox.

Expand image Applies To

  • Pages

    • Subtype - UIPart

    • Type - Control

Expand image Remarks

This property enables you to create a link from a Repeater or any other type of control to a Factbox. It could also be used to link two FactBoxes. For example, the Sales Order page (42), uses this property to update the Sales Line FactBox by creating a ProviderID link to the SalesLines FastTab.

Expand image See Also

Concepts

Properties


PushAction Property

PushAction Property

Sets the value that indicates whether the specified action should be performed immediately.

Expand image Applies To

The following elements on forms:

  • Check boxes

  • Command buttons

  • Option buttons

Expand image Property Value

Value | Description
OK | Close form and return OK
Cancel | Close form, do not return OK
LookupOK | Close lookup form and return OK
LookupCancel | Close lookup form, do not return OK
Yes | Close form and return Yes
No | Close form and return No
Close | Close the form
Stop | Stop processing
FormHelp | Show help for this form
RunObject | Run an application object
RunSystem | Run a system command (external program)
LookupTable | Perform a lookup into the current table

Expand image Remarks

The first eight actions specified in the list return an action to the caller. For example, OK is used to close a form and return OK to the caller. If you choose RunObject, you will have to specify the application object to run by using the RunObject Property. If the object you choose is a form, you can specify how to run this form further by using the RunFormView Property, RunFormLink Property, RunFormLinkType Property and RunFormOnRec Property.

If you choose RunSystem, use the RunCommand Property to specify the external program to run (including command-line parameters).

Expand image See Also

Reference

InvalidActionAppearance Property


RecordSeparator Property

RecordSeparator Property

Sets the string that is to be used to separate records.

Expand image Applies To

  • Dataports

  • XMLports

Expand image Property Value

Value | Description
<None> | There will no be RecordSeparator
<NewLine> (default) | Any combination of CR and LF characters
<CR/LF> | CR followed by LF
<CR> | CR alone
<LF> | LF alone
<TAB> | Tabulator alone
Other strings | The literal string entered

Expand image Remarks

The strings in the preceding table must be entered literally, that is, the < and > characters must be entered. These special strings can be combined and can be mixed with other characters.

CR refers to the character with ASCII value 13.

LF refers to the character with ASCII value 10.

Expand image See Also

Concepts

Properties


ReqFilterFields Property

ReqFilterFields Property

Sets fields that are automatically included on the tab of the request form that is related to this data item. The user can set filters on these fields.

Expand image Applies To

  • Data items

  • Forms

  • Pages

Expand image Remarks

A comma-separated list of field names. The fields can be selected by clicking the AssistEdit button in the Value field of this property.

When the request form is in use, the user will be able to add other fields and set filters on these fields.

Even so, it may still be a good idea to use this property: if the underlying table has many fields, the occasional user of the report or dataport may not easily find the relevant fields to filter.

If you do not want the user to be able to put filters on other fields, you must remove the request form by using the UseReqForm Property of the report or dataport, or remove the tab for this data item, by setting a specific key.

Expand image See Also

Reference

UseReqForm Property


ReqFilterHeading Property

ReqFilterHeading Property

Sets a caption for the request form tab that is related to this data item. The value is taken from the ReqFilterHeadingML Property if this property is set.

Expand image Applies To

Data items

Expand image Property Value

Any valid string. If ReqFilterHeadingML Property is set, the value for the selected language is used. If ReqFilterHeadingML Property is not set, the default is the name of the table that is the DataItemTable Property of the data item.

Expand image See Also

Reference

ReqFilterHeadingML Property
DataItemTable Property


ReqFilterHeadingML Property

ReqFilterHeadingML Property

Sets the text used as a ReqFilterHeading Property for a request form tab.

Expand image Applies To

Data items

Expand image Remarks

ReqFilterHeadingML is multilanguage enabled. This means that it can contain a list of text in different languages. The text that is used will be selected according to the current language setting of the user. The ReqFilterHeadingML property has the following format.

CopyCode image Copy Code
<Language ID>=< reqfilterheading >

<Language ID> is a Windows standard three-letter language ID and <reqfilterheading> is the caption text for this language. Semicolons separate entries.

You can enter values for the ReqFilterHeadingML property in two ways:

  • If you enter a ReqFilterHeading, this value will be inserted in ReqFilterHeadingML as the value for the language that is currently selected. If the language is set to Danish when a value is entered in ReqFilterHeading, ReqFilterHeadingML will be updated with a DAN=<value> string. You have to use the abbreviated name (DAN for Danish, for example) of the languages.

  • When you click the AssistEdit button in the ReqFilterHeadingML Value field, the Multilanguage Editor opens. This is a form with two columns: Language and Value. The Language column is populated with all languages defined by Windows. For your convenience, the names, not the abbreviated names, of the languages are displayed. The ReqFilterHeadingML value for a language is added by entering a value in the Value field for that language. You have to close this form by clicking OK. If it is closed by pressing the ESC key, the ReqFilterHeadingML field is not updated.

Expand image See Also

Concepts

Working with Multilanguage Functionality


RightMargin Property

RightMargin Property

Sets the right margin of a report. The unit of measure is 1/100 mm.

Expand image Applies To

Reports

Expand image Remarks

A right margin specified in the Page Setup dialog box overrides RightMargin.

Some printers require a minimum margin. If you specify a margin that is smaller than the minimum margin, the minimum margin will be used when printing.

The default is 0 mm.

The RightMargin property is not supported on client report definition (RDLC) report layouts. The create layout suggestion function sets the margin values on RDLC report layouts.

Expand image See Also

Reference

LeftMargin Property


RowHeight Property

RowHeight Property

Sets the height of the rows in a table box.

Expand image Applies To

  • Matrix boxes

  • Table boxes

Expand image Remarks

Enter the row height in increments of 1/100 of a millimeter.

Expand image See Also

Concepts

Properties


RunCommand Property

RunCommand Property

Sets an operating system command. This property is used as a parameter to the PushAction Property.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Menu items

  • Option buttons

Expand image Remarks

To use this property, first select RunSystem in the PushAction Property property. Then you can enter any operating system command in this property. Separate any parameters with spaces.

Expand image See Also

Reference

InvalidActionAppearance Property
RunObject Property
RunFormView Property
RunFormLink Property
RunFormLinkType Property


RunFormLink Property

RunFormLink Property

Sets up a link to the form you are launching. This property is used as a parameter to the PushAction Property.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Menu items

  • Option buttons

  • Pages

Expand image Remarks

For example, if the current form is the customer card and you need to provide a way to see the outstanding sales orders for the current customer, you would select RunObject in the PushAction property and use the RunObject Property to run the customer sales orders form. In this property you would select the Customer No. field as the link between the two forms.

For an example of how to use RunFormLink to launch a page from an action in the RoleTailored client, see Walkthrough: Adding Actions to a Customer List Page.

Expand image See Also

Reference

RunFormView Property
RunFormLinkType Property


RunFormLinkType Property

RunFormLinkType Property

Sets the type of link to the form you are launching. This property is used as a parameter to the PushAction Property.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Menu items

  • Option buttons

Expand image Property Value

Value | Description
OnOpen (default) | Form is opened
OnUpdate | Form is updated or the user changes records

Expand image Remarks

For example, suppose the current form is the customer card and you are providing a way to see the outstanding sales orders for the current customer. You would select RunObject in the PushAction property and use the RunObject Property to run the customer sales orders form. Then you would select the Customer No. field as the RunFormLink Property between the two forms. This property defines when to execute the link between the two forms.

Expand image See Also

Reference

RunFormView Property


RunFormOnRec Property

RunFormOnRec Property

Sets the same record on the form you launch from this control as is already displayed on the current form. This property is used as a parameter for the PushAction Property.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Menu items

  • Option buttons

  • Pages

Expand image Property Value

Yes if the current record on the form that you will launch from this control is displayed; otherwise, No. The default is No.

Expand image Remarks

For example, suppose the current form is the sales order and you are providing a way to see the sales statistics for the current customer. You would select RunObject in the PushAction property and use the RunObject Property to run the sales statistics form. In this property you could select Yes to display the same record on both forms.

Expand image See Also

Reference

RunFormView Property
RunFormLink Property


RunFormView Property

RunFormView Property

Sets a specific table view for the form or page that you launch from this control. This property is used as a parameter to the PushAction Property.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Menu items

  • Option buttons

  • Pages

Expand image Remarks

The table view is the view of the table that you present to the user. You determine what records the user can see by setting filters, determining the sorting order, and selecting the keys.

You can use this property to indicate how information should be sorted.

Expand image See Also

Reference

RunObject Property
RunFormLinkType Property
RunFormLink Property


RunObject Property

RunObject Property

Sets the object you want to run immediately. This property is used as a parameter to the PushAction Property.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Menu items

  • Option buttons

  • Pages

Expand image Remarks

To use this property, first select RunObject in the PushAction property. Then use this property to select the object you want to run.

Use the following properties to set parameters for the object you want to run:

  • RunFormView Property

  • RunFormLinkType Property

  • RunFormLink Property

Expand image See Also

Reference

RunFormView Property
RunFormLinkType Property
RunFormLink Property


SaveColumnWidths Property

SaveColumnWidths Property

Sets whether to save the column widths in the form table boxes.

Expand image Applies To

Forms

Expand image Property Value

Yes if the column width settings are saved; otherwise, No. The default is Yes.

Expand image Remarks

If you choose to save this information, the column width settings are saved and applied the next time the user opens this form. This information saved in the .zup file, which is a user-specific file that contains user settings.

Expand image See Also

Concepts

Properties


SaveControlInfo Property

SaveControlInfo Property

Sets whether user-specific control information is saved for this form.

Expand image Applies To

Forms

Expand image Property Value

Yes if user-defined filters are saved; otherwise, No. The default is Yes.

Expand image Remarks

The control information includes which control was active when the user last closed the form as well as the row and column which were active at that time. If you choose to save this information, it will be used to place focus in the correct position the next time the form is opened.

The control information saved in the .zup file, which is a user-specific file that contains user settings.

Expand image See Also

Reference

SaveColumnWidths Property
SavePosAndSize Property
SaveTableView Property
SaveValues Property
SourceTablePlacement Property


SavePosAndSize Property

SavePosAndSize Property

Sets whether to save user-specific information about the size and placement of the form.

Expand image Applies To

Forms

Expand image Property Value

Yes if user-defined position and size information is saved; otherwise, No. The default is Yes.

Expand image Remarks

If you set SavePosAndSize to Yes, the form will be displayed in the same size and place as it appeared the last time that the user opened the form. This information is saved in the .zup file, which is a user-specific file that contains user settings.

Expand image See Also

Concepts

Properties


SaveTableView Property

SaveTableView Property

Sets whether to save the table view that the user has defined for this form and reapply it the next time the user opens the form.

Expand image Applies To

Forms

Expand image Property Value

Yes if a user-defined table view is saved; otherwise, No. The default is Yes.

Expand image Remarks

The table view is the view of the table that you present to the user. You determine what records the user can see by setting filters, determining the sorting order, and selecting the keys.

The last record that a user was viewing is recorded and saved in the .zup file, which is a user-specific file that contains user settings.

Expand image See Also

Reference

SourceTableView Property


SaveValues Property

SaveValues Property

Sets whether user-specific control values are saved for this form or page.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if user-defined control values are saved; otherwise, No. The default is No.

Expand image Remarks

In the Classic client, this information is recorded and saved in the .zup file, which is a user-specific file that contains user settings.

In the RoleTailored client, this information is saved in the Page Data Personalization table.

Expand image See Also

Concepts

Properties


SectionHeight Property

SectionHeight Property

Sets the height of a section. The unit of measure is 1/100 mm.

Expand image Applies To

Sections

Expand image Remarks

You can set this property manually for exact measurement, but usually the height of a section is set automatically by the Section Designer as sections are resized with the mouse or as fields are added to the sections.

The height of a section will always be made large enough when a control is added; that is, larger than the bounding box around the control.

Expand image See Also

Concepts

Properties


SectionWidth Property

SectionWidth Property

Sets the width of a section. The unit of measure is 1/100 mm.

Expand image Applies To

Sections

Expand image Remarks

You can set this property manually for exact measurement, but usually the width of a section is set automatically by the Section Designer as sections are resized with the mouse or as fields are added to the sections.

All sections in one report must have the same width. Therefore, if one section is resized horizontally, all other sections in that report will have their SectionWidth properties adjusted accordingly.

Expand image See Also

Concepts

Properties


ShapeStyle Property

ShapeStyle Property

Sets the style of a shape control.

Expand image Applies To

Shapes

Expand image Property Value

Value | Description
Rectangle (default) | A rectangle with square corners
Rounded rectangle | A rectangle with rounded corners
Oval | An oval
Triangle | A triangle
NWLine | A diagonal line (\)
NELine | A diagonal line (/)
HorzLine | A horizontal line
VertLine | A vertical line

Expand image See Also

Concepts

Properties


ShortCutKey Property

ShortCutKey Property

Sets a shortcut key for selecting a menu item.

Expand image Applies To

  • Forms

  • Menu items

  • Pages

Expand image Remarks

Pressing the key you designate with this property provides the same result as clicking the item.

Note Note

Some shortcut keys have default assignments—for example, Shift+F12 opens the Object Designer. Do not reuse shortcut keys that are already assigned. For a complete list of shortcut keys, see Keyboard Shortcuts for the Navigation Pane in the online Help for your Microsoft Dynamics NAV client.

Expand image See Also

Concepts

Properties


ShowAsTree Property

ShowAsTree Property

Sets the indentation of rows on a List Page to Tree View. If you enable this property you can expand or collapse indented rows on a List Page.

Expand image Applies To

  • Pages

    • Subtype - Repeater

    • Type - Group

Expand image Property Value

Yes if a tree view is required; otherwise, No. The default is No.

Expand image See Also

Concepts

Properties


ShowCaption Property

ShowCaption Property

Sets whether the caption set using Caption Property is displayed for the given object.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Menu buttons

  • Option buttons

Expand image Property Value

Yes if the caption is displayed; otherwise, No. The default is Yes.

Expand image See Also

Reference

Caption Property
CaptionML Property


ShowPrintStatus Property

ShowPrintStatus Property

Sets whether a window that shows the printing status of a report when it is run is displayed.

Expand image Applies To

Reports

Expand image Property Value

Yes if a status window is shown; otherwise, No. The default is Yes.

Expand image Remarks

Apart from showing the progress of the report, the window also contains a Cancel button that will cause the processing and printing of the report to terminate, when clicked. If you set ShowPrintStatus to No, the user will not be able to stop the report prematurely.

If the ProcessingOnly Property is Yes, there will be no status dialog box, even if ShowPrintStatus is Yes. If you need a status dialog box, you must create one yourself.

Expand image See Also

Reference

ProcessingOnly Property


ShowStatus Property (Dataports)

ShowStatus Property (Dataports)
See Also
CollapseAll image

Sets whether a status window is displayed showing dataport run status.

Expand image Applies To

Dataports

Expand image Property Value

Yes if a status window is shown; otherwise, No. The default is Yes.

Expand image Remarks

Apart from showing the progress of the dataport, the window also contains a Cancel button that causes the dataport processing to terminate when clicked. If you set ShowStatus to No, the user will not have the opportunity to stop the dataport prematurely.

Expand image See Also

Concepts

Properties


SignDisplacement Property

SignDisplacement Property

Sets a value to shift negative values to the right for display purposes only. You can shift negative values in increments of 1/100 of a millimeter.

Expand image Applies To

Text boxes

Expand image Remarks

For example, if you enter 600 (6 millimeters) you would see a result similar to:

(+)999888777

(+)123456789

(-) 123456789

(-) 999888777

(+)987654321

Expand image See Also

Concepts

Properties


SingleInstance Property

SingleInstance Property

Sets whether a single instance of the codeunit and codeunit variables are instantiated.

Expand image Applies To

Codeunits

Expand image Property Values

Yes if only one instance of a codeunit that makes it a single instance codeunit is set; otherwise, No. The default is No.

Expand image Remarks

When you set this property to Yes on a codeunit, all codeunit variables that use this codeunit use the same instance. That is, all codeunit variables of this codeunit use the same set of internal variables when the code is running on the same client. The codeunit remains instantiated until you close the company.

The following example shows how you can use the SingleInstance property.

Two forms can connect to the same codeunit.

On Form1:

Codeunit1.SetNumber(100);

On Form2:

Number := Codeunit1.GetNumber();

 MESSAGE(Format(Number));

The SingleInstance property in Codeunit1 is set to Yes. Form1 calls a function on Codeunit1 and sets the parameter to 100. Codeunit1 saves this parameter in a local variable. Form2 is now able to get the parameter value (=100) from Codeunit1. A message is displayed.

Expand image See Also

Concepts

Properties


Sizable Property

Sizable Property

Sets whether the form border can be resized.

Expand image Applies To

Forms

Expand image Property Value

Yes if the user can resize the form; otherwise, No. The default is Yes.

Expand image Remarks

If this property is set to Yes, then a Size option also appears on the Control menu for the form. To access the Control menu, use ALT+- (hyphen) for forms, use ALT+SPACEBAR for some tools and for the application window, or click the horizontal bar in the upper left corner of the frame.

This setting is checked when the form is opened. This property does not affect associated subforms.

Expand image See Also

Concepts

Properties


SourceExpr Property

SourceExpr Property

Sets the source expression for this control.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Dataport fields

  • Forms

  • Indicators

  • Menu buttons

  • Option boxes

  • Pages

  • Picture boxes

  • Text boxes

Expand image Remarks

A source expression is a C/AL expression that defines where to find the value of a control. The source expression is evaluated when updates are performed. A source expression can be as simple as the name of a table field; it can also be a complex C/AL expression.

For some controls, the source expression has a special meaning:

  • For a menu item, the setting of SourceExpr must evaluate to true or false. true means that the menu item will appear checked, false means that it will appear unchecked (normal).

  • For a control that has a BitmapList Property, the (integer) source expression is used to select a bitmap from the list.

Expand image See Also

Reference

BitmapList Property


SourceField Property

SourceField Property

Sets the field that you want to map XML data to.

Expand image Applies To

XMLports

Expand image Remarks

This property is only available if you have selected Field in the SourceType Property.

You need to select Table as the SourceType of the parent tag and specify the table in the SourceTable Property.

The SourceField property is related to the DataSource field in XMLport Designer.

When you click the AssistButton in the Value field for the SourceField property, the window that opens lists all the tables that have been defined as part of this XMLport and you can select a field from one of these tables.

If you have given a table a variable name in the Properties window for that element, this name is displayed in the Field Lookup window.

When you select the variable name that you have given the current table, the selection is displayed in the DataSource field of XMLport Designer and in the Value field of the SourceField property in the following format:

CopyCode image Copy Code
tablevariablename::fieldname

Expand image See Also

Reference

SourceType Property
SourceTable Property


SourceTable Property

SourceTable Property

Sets the ID of the table from which this form will display records.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

Use the Lookup button to select the table you want.

Expand image See Also

Concepts

Properties


SourceTable Property (XMLports)

SourceTable Property (XMLports)
See Also
CollapseAll image

Sets the table to which you want to map XML data or the table that you want to export data from.

Expand image Applies To

XMLports

Expand image Remarks

This property is available if you selected Table in the SourceType Property.

The values of the VariableName Properties and the SourceTable properties correspond to the contents of the DataSource field in XMLport Designer. The values that you enter in these properties in the Properties window are shown in the DataSource field in XMLport Designer.

If you have defined a text variable, you can only see the name of the text variable in the DataSource field in the XMLport Designer. For example, if you have defined a table as an XML item, the DataSource field can display the following information.

Properties window SourceTable | Properties window VariableName | XMLport Designer
Customer | <Customer> default | <Customer>(Customer)
Customer | Cust. | Cust.<Customer>

Expand image See Also

Reference

SourceType Property
VariableName Properties


SourceTablePlacement Property

SourceTablePlacement Property

Sets the record to be displayed when the user opens the form.

Expand image Applies To

Forms

Expand image Property Value

Value | Description
Record | A specific record
First | The first record in the table
Last | The last record in the table
Saved (default) | The record being shown the last time the user displayed the form

Expand image Remarks

If you choose Record, you must use the SourceTableRecord Property to define the record you want displayed. This property setting is checked when the form is opened. The last record a user was viewing is recorded and saved in the .zup file, which is a user-specific file that contains user settings.

Expand image See Also

Reference

SourceTableRecord Property


SourceTableRecord Property

SourceTableRecord Property

Sets a specific record to display when the form opens. Use this property in combination with the SourceTablePlacement property.

Expand image Applies To

Forms

Expand image Remarks

To use this property, you must also select Record in the SourceTablePlacement Property. Use the AssistEdit button to select the record you want to display. This property is evaluated when the form is opened.

Expand image See Also

Reference

SourceTablePlacement Property


SourceTableTemporary Property

SourceTableTemporary Property

Sets whether the source table is a temporary table.

Expand image Applies To

  • Forms

  • Pages

Expand image Property Value

Yes if you want the source table to be a temporary table; otherwise, No. The default value is No.


SourceTableView Property

SourceTableView Property

Sets the key, sort order, and filter you want to use to determine the view of the source table presented to the user.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

Use the AssistEdit button to help you select the key, sort order, and filter. This property setting is checked when the form is opened.

Expand image See Also

Concepts

Properties


SourceTableView Property (XMLports)

SourceTableView Property (XMLports)
See Also
CollapseAll image

Sets the key used to sort data in the source table for the XML item.

Expand image Applies To

XMLports

Expand image Remarks

The AssistButton in the Value field for this property opens the Table View window that allows you to specify sort order and the key that is used to sort the table data. You can also place a filter on the table.

Expand image See Also

Concepts

Properties


SourceType Property

SourceType Property

Sets what a particular tag in the XMLport Designer corresponds to in the Microsoft Dynamics NAV database.

Expand image Applies To

XMLports

Expand image Property Value

Value Description

Text

The XML data in the object denoted by the NodeName Property cannot be mapped directly to the Microsoft Dynamics NAV database or when the database does not need the information. The name of the Text field in the XMLport Designer is put into a global text variable.

This variable functions just like a C/AL Global variable. However, it is not visible in C/AL Globals window but it is visible in the C/AL Symbol Menu.

Table

The object denoted by the NodeName Property corresponds to a Microsoft Dynamics NAV table. You should also select this value when a Microsoft Dynamics NAV table record needs to be initialized.

Field

Access is required to a field in the database. For this selection to be valid, you must first have declared a table as the parent of this object or attribute. Failure to do so will cause an error to occur when you try to compile the XMLport object.

Expand image Remarks

This property is directly related to the SourceType field in the XMLport Designer.

Expand image See Also

Reference

NodeName Property


SQL Data Type Property

SQL Data Type Property

Sets the data type that you want to allow in a code field.

Expand image Applies To

Code fields in Microsoft Dynamics NAV with Microsoft SQL Server.

Expand image Remarks

The values available are Varchar, Integer, BigInteger, and Variant. Leaving the value set at <Undefined>means that you accept the default setting, which is Varchar.

Note Note

The Variant option is represented by the SQL_VARIANT SQL data type that has been introduced in SQL Server 2000 and is not supported by SQL Server 7.0. This means that selecting Variant as the SQL Data Type property when creating or modifying a table on SQL Server 7.0 results in an error.

Varchar

If you set SQL Data Type to Varchar, all the values in the field are compared and sorted as character data, including numeric values.

Integer

If you set SQL Data Type to Integer, then the following are true:

  • All the values in the field are compared and sorted as integers. No alphanumeric values can be stored in the field.

  • If you enter negative values in the column outside Microsoft Dynamics NAV using external tools, they cannot be read into Microsoft Dynamics NAV.

  • The value "0" (zero) is used to represent an empty string in Microsoft Dynamics NAV.

  • Non-numeric code values or any numeric values beginning with "0" (zero) cannot be entered in the code field.

Variant

If you set SQL Data Type to Variant, then the following are true:

  • The values in the field are compared and sorted according to their base data type. Numeric values are sorted after alphanumeric values.

  • Data that is entered into the code field in Microsoft Dynamics NAV is stored as either the Varchar or Integer base data type, depending on the value that has been entered.

  • Any value beginning with "0" (zero) can be entered in the code field and is stored as an Integer base data type.

    Note Note

    You can change the SQL Data Type of a code field from Varchar or Integer to Variant and the data in the column is changed accordingly. You cannot change the SQL Data Type of a code field from Variant to Varchar or Integer, unless there are no rows in the table or unless the field contains only an empty string in every row.

Expand image See Also

Reference

Integer Data Type
BigInteger Data Type
Variant Data Type

Concepts

Properties


SQLIndex Property

SQLIndex Property

Sets the actual fields that are used in the corresponding index on SQL Server.

Expand image Applies To

Keys

Expand image Remarks

This property allows you to define the fields that are used in the SQL index.

The fields in the SQL index can:

  • Differ in number from the fields defined in the key in Microsoft Dynamics NAV—there can be fewer fields or more fields.

  • Be arranged in a different order.

If you use this property to define an index on a key that is not the primary key, then the index that is created contains exactly the fields that you specify and will not be a unique index. A unique index will only be created if it contains all of the primary key fields.

If you use this property to define an index for the primary key, it must include all the fields defined in the primary key. You can add extra fields and you can rearrange the fields to suit your needs.

Expand image See Also

Tasks

How to: Define Primary and Secondary Keys


Standard day/time unit Property

Standard day/time unit Property

Sets the unit of measure that is used when you enter data into duration fields.

Expand image Applies To

Fields of the Duration data type.

Expand image Remarks

The units of measure that you can enter are: day, hour, minute, second, and millisecond.

The default value is hour.

Duration is always stored as milliseconds.

Expand image See Also

Concepts

Properties


StartPos Property

StartPos Property

Sets the starting position of a field in a data item of a dataport.

Expand image Applies To

Fields in dataports

Expand image Remarks

Set the integer value of StartPos to the first character in this field. The first position is 1.

The setting of this property is only used if FileFormat Property is Fixed. If it is, StartPos and Width Property (Dataport field) are used to define fields when records are imported or exported.

Expand image See Also

Reference

FileFormat Property
Width Property (Dataport field)


Style Property

Style Property

Sets a value that determines how a text in a field on a page is formatted.

Expand image Applies To

  • Page field controls that contain text.

Expand image Property Value

The Style formatting that is applied to a page in edit mode is different than the formatting that is applied in view mode.

Value | Format in Edit mode | Format in View mode
Strong | Bold | Bold
Attention | Red | Default
Favorable | Bold + Green | Bold
Unfavorable | Bold + Italic + Red | Bold + Italic

Expand image Remarks

The Style property works together with the value StyleExpr Property to determine whether the field is formatted. If the StyleExpr Property evaluates to true, then the value of the field is formatted as specified by the Style property.

By default, the Style property is not set.

This property is not supported if one of the following data types is used for the SourceExpr of the field:

  • Code

  • Boolean

  • Binary

  • BLOB

  • GUID

  • RecordID

Expand image See Also

Tasks

How to: Style Field Text on a Page


StyleExpr Property

StyleExpr Property

Sets whether the format that is specified in the Style Property is applied to text in a field.

Expand image Applies To

  • Page field controls that have text

Expand image Remarks

If the StyleExpr property evaluates to true, then the value of the field is formatted as specified by the Style Property. You can use set the value to true or false, or you can use a variable that evaluates to true or false. The property's default value is false.

Note Note

To use a variable for the StyleExpr property, the IncludeInDataSet Property of the variable must be set to Yes.

Expand image See Also

Tasks

How to: Style Field Text on a Page


SubFormID Property

SubFormID Property

Sets a subform that will be opened in a subform control.

Expand image Applies To

Subforms

Expand image Remarks

Enter the ID, either the number or the name, of the subform.

Expand image See Also

Concepts

Properties


SubFormLink Property

SubFormLink Property

Sets a link to a subform from the main form or to a Factbox from a page.

Expand image Applies To

  • Pages

  • Subforms

Expand image Remarks

The link is updated when the current record changes.

For an example of how to use SubFormLink to update the content of a FactBox in the RoleTailored client as different items are selected in a list page, see Walkthrough: Adding a FactBox to the Customer List Page.

Expand image See Also

Concepts

Properties


SubFormView Property

SubFormView Property

Sets the table view for a subform.

Expand image Applies To

  • Pages

  • Subforms

Expand image Remarks

The table view is the view of the table that you present to the user. You determine what records the user can see by setting filters, determining the sorting order, and selecting the keys.

You can use this property to sort the information in the table for display in this subform. Use the AssistEdit button to help you set the table view for the subform.


SubType Property

SubType Property

Sets additional information about what will be contained in the field.

Expand image Applies To

BLOB fields

Expand image Property Value

Value | Description
Bitmap | For storing bitmaps
Memo | For storing memos
User-Defined (default) | For user defined information

Expand image Remarks

When you use the C/AL functions IMPORT Function (BLOB) and EXPORT Function (BLOB), a dialog box is provided from which the user can pick the BLOB to import or export.

Based on your selection, only the appropriate file types are shown. For example, if you select Bitmap, only files with the extension .bmp are shown. If you select Memo, only files with the extension .txt are shown. If you select User-Defined, all files are shown.

Expand image See Also

Reference

IMPORT Function (BLOB)
EXPORT Function (BLOB)


SubType Property (Codeunit)

SubType Property (Codeunit)
See Also
CollapseAll image

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Sets the codeunit to functions as a normal, test, or test runner codeunit.

Expand image Applies To

Codeunits

Note Note

The SubType property is only visible if the Show C/AL Testability properties option of the Classic client is set to Yes. To change this setting, on the Tools menu, click Options.

Expand image Property Value

Value | Description
Normal | A normal codeunit. This is the default setting.
Test | A test code includes C/AL functions that test the application. For more information, see How to: Create Test Codeunits and Test Functions.
TestRunner | A test runner codeunit manages the execution of one or more test codeunits. For more information, see How to: Create a Test Runner Codeunit.

Expand image Remarks

In Microsoft Dynamics NAV 2009 SP1, you can create test codeunits and test runner codeunits to test your application.

You write test functions as C/AL code in the test codeunits. When a test codeunit runs, it executes the OnRun function and then executes each test function in the codeunit, records the outcome in a log, and displays the results in a message window. The continuation of the test function run is dependent on successful run of the OnRun function. The difference between a normal codeunit and a test codeunit is their execution at run time. When a normal codeunit is run, if one of its functions fails, then the codeunit is terminated. When a test codeunit is run, if a function fails, then the function is terminated, but the codeunit continues to run the remaining functions.

A test runner codeunit runs the test codeunits that are programmed to run from its OnRun trigger. When a test runner codeunit runs, it does the following:

  • Calls the OnBeforeTestRun Trigger before each test codeunit, and the OnRun function and test function is executed.

  • Calls the OnAfterTestRun Trigger after each test code unit, and the OnRun function and test function is executed.

  • Indicates that a test function has failed if it invokes the user interface.

For more information, see Testing the Application.

Expand image See Also

Tasks

How to: Create Test Codeunits and Test Functions
How to: Create Handler Functions
Walkthrough: Testing Vendor Discount

Concepts

Testing the Application
Developing Codeunits


SumIndexFields Property

SumIndexFields Property

Sets the SumIndexFields for the key, if applicable.

Expand image Applies To

Keys

Expand image Remarks

You can select up to 20 SumIndexFields for each key.

Changing existing keys may affect the behavior of the application since other parts of your application may depend on the existence of certain keys.

Expand image See Also

Concepts

SumIndexFields
SumIndexFields Overview


SystemPartID Property

SystemPartID Property

Sets pre-defined system parts.

Expand image Applies To

  • Pages

    • Type - Control

    • Subtype - UIPartType

Expand image Remarks

The available options are: Outlook, Notes, MyNotes, RecordLinks, or None.

Expand image See Also

Reference

PartType Property
PagePartID Property
ChartPartID Property


TableBoxID Property

TableBoxID Property

Sets the ID of the table box that displays the source table associated with this form.

Expand image Applies To

Forms

Expand image Remarks

If there is more than one table box on the form, use this property to specify the table box ID of the main or primary table box. This property is evaluated when the form is opened.

Expand image See Also

Concepts

Properties


TableIDExpr Property

TableIDExpr Property

Sets the ID of the table to which you want to apply a table filter.

Expand image Applies To

Fields

Expand image Remarks

The field must be of the TableFilter Data Type. The Table ID expression must be of the Integer Data Type and is typically the Object ID of the table. To understand how this property is applied, see the Permission table.

Expand image See Also

Reference

TableFilter Data Type


TableNo Property

TableNo Property

Sets the source table number, if any, for this codeunit.

Expand image Applies To

Codeunits

Expand image Remarks

Use the lookup to select the appropriate table number. If the codeunit can apply to any table, then choose Undefined.

If you specify a table number for this property, then you can use the CurrRec global variable in the codeunit and use the Codeunit.RUN Function (Codeunit) to execute the code unit

Expand image See Also

Reference

Codeunit.RUN Function (Codeunit)


TableRelation Property

TableRelation Property

Sets relationships (links) to other tables. For example, if you want to provide a lookup into another table, enter the name of that table in this property.

Expand image Applies To

  • Fields

  • Text boxes

Expand image Remarks

The TableRelation property lets you establish lookups into other tables. For example, on the Item card you can select a vendor from who you usually purchase an item. This is done through a table relationship.

This property is also used to define where to look to validate entries.

In addition, when you choose the option to test the relationships between primary and secondary indexes, this property defines what to test. This option is one of the Database options on the File menu.

Expand image See Also

Reference

ValidateTableRelation Property
TestTableRelation Property


Temporary Property

Temporary Property

Sets whether a temporary table is created.

Expand image Applies To

Record variables

Expand image Remarks

Changes made to a temporary table are not stored to a database.

Expand image See Also

Concepts

Properties


Temporary (XMLports) Property

Temporary (XMLports) Property

Sets whether a temporary table is created to store the records imported using the XMLport.

Expand image Applies To

Record variables

Expand image Remarks

The following are two examples of how to use temporary tables with XMLports.

If the data that you are importing has a different structure than the table in Microsoft Dynamics NAV that you want to insert it into, you could import the data into a temporary table. The temporary table holds the data in cache without writing it to the database. You can then modify the data before inserting it into the database.

If the data that you are importing contains a record that already exists in the database, you cannot import it because C/SIDE only allows you to insert new records into the database. To avoid this problem, you can import the data into a temporary table, locate the record and use C/AL code to modify it and then insert it into the database. For more information, see XMLport Document Containing Data in Different Scopes.

Expand image See Also

Reference

Temporary Property


TestTableRelation Property

TestTableRelation Property

Sets whether to include this field when evaluating field relations between primary and secondary indexes.

Expand image Applies To

Fields

Expand image Property Value

Yes if you want to test the table relationship for this field; otherwise, No. The default is Yes.

Expand image Remarks

You may want to use this property to exclude certain fields from the table relation test. For example, if a table in your application has a field that is a foreign key, but records from the other table may have been deleted, then you would not want to test the relationship with this table. Only set this property to No if you are certain that testing this relationship would only cause errors that do not compromise the consistency of your application tables.

This test is available from the Database option on the File menu. You can use this property to limit the number of relationships that are tested.

If you set the ValidateTableRelation property to No, then you should also set the TestTableRelation property to No. Otherwise, a database test on the field relations in a database may fail.

Expand image See Also

Reference

TestTableRelation Property
ValidateTableRelation Property


TextType Property

TextType Property

Sets the type of text this element or attribute contains.

Expand image Applies To

XMLports

Expand image Property Value

BigText if you want to display large text ; otherwise, Text. The default is Text.

Expand image See Also

Concepts

Properties


TimerInterval Property

TimerInterval Property

Sets the interval for executing code contained in the active form's OnTimer Trigger.

Expand image Applies To

Forms

Expand image Remarks

The default value of this property is zero (0). This means that code is not executed in the OnTimer trigger.

You can specify a TimerInterval value in milliseconds ranging from zero to the highest defined integer, which corresponds to approximately 25 days.

When you open a form for which you have specified a TimerInterval value, the OnOpenForm Trigger is executed. A timer then starts to count the TimerInterval in milliseconds. After the specified interval has elapsed, the OnTimer Trigger is executed. The timer then resets to zero and the process is repeated until the form is closed.

In some cases, the TimerInterval value specified may be too short to allow for complete execution of the OnTimer trigger before starting the next instance of the trigger. In this case, the number of overlapping instances is noted and the trigger is executed continuously for as long as necessary.

Problems with your computer's operating system can affect the performance of the timer.

Expand image See Also

Reference

OnOpenForm Trigger
OnTimer Trigger


Title Property

Title Property

Set whether the first letter in each word the user types is capitalized.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Property Value

Yes if you want to capitalize the first letter in each word; otherwise, No. The default is No.

Expand image Remarks

The control and the field settings are checked during validation.

Expand image See Also

Concepts

Properties


ToolTip Property

ToolTip Property

Sets whether tooltips are provided for the given object. The tooltip value is taken from the ToolTipML Property if this property is set.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Pages

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

The default is an empty string, which means there will be no tooltip.

The ToolTip property is not supported in the RoleTailored client in Microsoft Dynamics NAV 2009.

Expand image See Also

Reference

ToolTipML Property

Concepts

Working with Multilanguage Functionality


ToolTipML Property

ToolTipML Property

Sets the text used for the tooltip of a control.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Pages

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

ToolTipML is multilanguage enabled. This means that it can contain a list of strings for use by different languages. The text that is used is selected according to the user's current language setting. For more information, see Working with Multilanguage Functionality.

The ToolTipML property value has the following format.

CopyCode image Copy Code
<Language ID>=<tooltip>

<Language ID> is a Windows standard three-letter language ID and <caption> is the caption text for this language. Semicolons are used to separate entries.

In the following example, values are set for Danish (DAN) and English (ENG).

CopyCode image Copy Code
DAN=Dette felt indeholder kundens navn;ENG=This field contains the customer name

How to Enter ToolTipML Values

You can enter values for the the ToolTipML property in two ways.

  • Enter a ToolTip Property value. This value is inserted in ToolTipML as the value for the language that is currently selected. If the language is set to Danish when a value is entered in ToolTip, ToolTipML is updated with a DAN=<value> string. You have to use the abbreviated language name (for example, DAN for Danish).

  • Click the AssistEdit button in the ToolTipML Value field to open the Multilanguage editor. This is a form with two columns: Language and Value. The Language column is populated with all languages defined by Windows. Enter tooltip text in the Value field for the appropriate language and then click OK to close the editor. If you press the ESC key to close the editor, the ToolTipML field is not updated.

Expand image See Also

Reference

ToolTip Property


TopLineOnly Property

TopLineOnly Property

Sets whether to display only the top line of the frame with the caption left-aligned.

Expand image Applies To

Frames

Expand image Property Value

Yes if you want to display only the top line of the frame; otherwise, No. The default is No.

Expand image See Also

Concepts

Properties


TopMargin Property

TopMargin Property

Sets the top margin of a report. The unit of measure is 1/100 mm.

Expand image Applies To

Reports

Expand image Remarks

A top margin specified in the Page Setup dialog box overrides TopMargin.

Some printers require a minimum margin. If you specify a margin that is smaller than the minimum margin, the minimum margin will be used when printing.

The default is 20 mm.

The TopMargin property is not supported on client report definition (RDLC) report layouts. The create layout suggestion function sets the margin values for RDLC report layouts.

Expand image See Also

Reference

BottomMargin Property


TotalFields Property

TotalFields Property

Sets the value to indicate the data item fields for which totals should be maintained.

Expand image Applies To

Data items on Classic report layouts

Expand image Remarks

If this property is used in conjunction with the GroupTotalFields Property, totals can be maintained for both the groups that are defined and all records that are output; if used by itself, TotalFields will maintain totals for all records.

Enter a comma-separated list of field names. The fields can be selected by clicking the AssistEdit button in the Value field of this property.

The totals are printed by placing controls that have the fields that are indicated in TotalFields as their source expressions in a Footer, GroupFooter, TransHeader, or TransFooter section of the data item.

Expand image See Also

Reference

GroupTotalFields Property


TransactionType Property

TransactionType Property

Sets the transaction type.

Expand image Applies To

  • Dataports

  • XMLports

Expand image Remarks

There are four basic transaction types: Browse, Snapshot, UpdateNoLocks, and Update. Each transaction type defines the behavior of a transaction in Microsoft Dynamics NAV and takes effect from the beginning of a transaction.

Additionally, there is a Report option that maps to one of the basic options. This enables a report to use the most concurrent read-only form of data access for the connected server. When you use Microsoft Dynamics NAV Database Server, it maps to Snapshot and when you use SQL Server, it maps to Browse.

The following table shows transaction behavior when using SQL Server.

Transaction Type Behavior

Browse

This is a read-only transaction. Modifications cannot occur within the transaction. All read operations are performed with READ UNCOMMITTED locking. Therefore, no locks are placed and locks placed by other sessions are not honored. This means that it is possible to read uncommitted data.

Snapshot

This is a read-only transaction. Modifications cannot occur within the transaction. All read operations are performed with SERIALIZABLE locking. Therefore, share-locks are placed and maintained until the end of the transaction. This guarantees a consistent snapshot of the data read within the transaction.

Microsoft's definition of "SERIALIZABLE" is as follows, "A transaction isolation level that ensures that a database changes from one predictable state to another. If multiple concurrent transactions can be executed serially, and the results are the same, the transactions are considered serializable."

For more information about SERIALIZABLE locking, consult Microsoft's SQL Server documentation.

UpdateNoLocks

This is an update transaction. Modifications can occur within the transaction. The locking behavior for read operations on each table is the same as for the Browse transaction type until the table is either modified by a write operation or locked with the Record.LOCKTABLE function. From this point until the end of the transaction, all read operations are performed with both SERIALIZABLE and UPDLOCK locking.

This transaction type improves concurrency for all tables that users access within the transaction by delaying locking as much as possible. However, the disadvantage is that you must know when to lock the tables for the required transaction behavior.

This is the default transaction type if you have not specified a type with the CURRENTTRANSACTIONTYPE Function (Database).

Update

This is an update transaction. Modifications can occur within the transaction. The locking behavior for read operations on each table is the same as for the Snapshot transaction type until the table is either modified by any write operation or locked with the Record.LOCKTABLE function. From this point forward, all read operations are performed with both SERIALIZABLE and UPDLOCK locking.

This transaction type provides full transaction isolation from the beginning of the transaction, regardless of the lock status of tables that users access within the transaction.

Expand image See Also

Reference

CURRENTTRANSACTIONTYPE Function (Database)


UpdateOnAction Property

UpdateOnAction Property

Sets whether to save the current record before it executes the action associated with this control and then updates the form after it completes the action.

Expand image Applies To

  • Command buttons

  • Check boxes

  • Option buttons

  • Menu items

Expand image Property Value

Yes if you want to update this form before and after it executes the action; otherwise, No. The default is Yes.

Expand image See Also

Concepts

Properties


UpdateOnActivate Property

UpdateOnActivate Property

Sets whether the form is updated when it is activated.

Expand image Applies To

Forms

Expand image Property Value

Yes if you want to update this form when activated; otherwise, No. The default is No.

Expand image See Also

Concepts

Properties


UseReqForm Property

UseReqForm Property

Sets whether the user of the report or dataport is presented with a request form.

Expand image Applies To

  • Dataports

  • Reports

Expand image Property Value

Yes if you want to show a request form; otherwise, No. The default is Yes.

Expand image Remarks

If UseReqForm is No, a request form is not shown. This means that the user will not be able to choose a sort order or set filters, and that the print dialog box will not be shown (a report will be printed and a dataport will be run immediately.)

Expand image See Also

Concepts

Properties


UseSystemPrinter Property

UseSystemPrinter Property

Sets which printer is suggested when the report is run.

Expand image Applies To

Reports

Expand image Property Value

Yes if you want the system default printer to be used; otherwise, No. The default is No.

Expand image Remarks

The user will be able to select another printer at runtime if the UseReqForm Property is Yes.

If the UseSystemPrinter property is set to No, but there is no specific printer defined for the User/Report combination, the system default printer will be suggested.

Expand image See Also

Reference

UseReqForm Property


ValidateTableRelation Property

ValidateTableRelation Property

Sets whether to validate a table relationship.

Expand image Applies To

  • Fields

  • Text boxes

Expand image Property Value

Yes if you want to validate the table relationship; otherwise, No. The default is Yes.

Expand image Remarks

For fields, use this property to determine whether to validate the user's entry based on the information already in the table set up through the TableRelation Property property.

If you want to let users enter any value without validating the entry, then choose No. For example, on the item card, you can specify the vendor that you typically purchase the item from. Set this property to No to allow users to select a vendor that may not already be in the Vendor table.

For text boxes, use this property to determine whether to validate a table relationship.

If you set the ValidateTableRelation property to No, then you should also set the TestTableRelation property to No. Otherwise, a database test on the field relations in a database may fail.

Expand image See Also

Reference

TestTableRelation Property


ValuesAllowed Property

ValuesAllowed Property

Sets the values that are allowed in the field or text box.

Expand image Applies To

  • Fields

  • Forms

  • Pages

  • Text boxes

Expand image Remarks

Separate the values with a semicolon. The property setting is recursively checked during validation. For example, if you only want the user to enter 1, 3, or 5 in this field, enter 1;3;5 for this property.

Expand image See Also

Concepts

Properties


VariableName Properties

VariableName Properties

Sets a variable name for the table that you have specified in the SourceTable Property. It is also used to specify a variable name for a text that you have specified in the SourceType Property.

Expand image Applies To

XMLports

Expand image Remarks

The text or table variables that you define here act the same way as variables that are defined in the C/AL Globals window. However, these variables are only visible in the C/AL Symbol Menu.

The values of the VariableName and SourceTable Property correspond to the contents of the DataSource field in XMLport Designer. The values that you enter in these properties in the Properties window are shown in the DataSource field in XMLport Designer.

If you have defined a text variable, you can only see the name of the text variable in the DataSource field in XMLport Designer.

If you have defined a table as an XML item, the DataSource field can display the following information.

Properties window SourceTable | Properties window VariableName | XMLport Designer DataSource field
Customer | <Customer> default | <Customer>(Customer)
Customer | Cust. | Cust.<Customer>

Expand image See Also

Reference

SourceTable Property
SourceType Property


VertAlign Property

VertAlign Property

Sets how the data or the caption of the control is vertically aligned.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Labels

  • Menu buttons

  • Option buttons

  • Text boxes

Expand image Property Value

Value | Description
Top | To align the data at the top
Bottom (default for labels in column headings) | To align the data at the bottom
Center (default for labels, command buttons, menu buttons, check boxes, option buttons, text boxes) | To align the data in the center

Expand image Remarks

If you choose bottom or center, lines of the text are truncated, as needed.

This property is not supported in the RoleTailored client.

Expand image See Also

Reference

HorzAlign Property


VertGlue Property

VertGlue Property

Sets how to anchor the control vertically. You can anchor it to the top, bottom, or top and bottom of the form or subform.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Value | Description
Top (default) | At the top
Bottom | At the bottom
Both | To both the top and bottom

Expand image Remarks

If this control is contained in a table box, the setting for this control is ignored.

If you select Both, the control is resized when the user resizes the window.

The HorzGlue and VertGlue properties are not active during design, except for HorzGlue on columns.

This property is not supported in the RoleTailored client.

Expand image See Also

Reference

HorzGlue Property


VertGrid Property

VertGrid Property

Sets the distance between vertical grid lines in the form and sections designers. The grid is shown as one dot per five grid distances. The unit of measure is 1/100 mm.

Expand image Applies To

  • Forms

  • Classic report layouts (sections)

Expand image Property Value

Value | Description
default (1.1 millimeter) | Use the default setting
infinite | Display no vertical grid
(the number; 0 means no grid) | Display a custom grid you define

Expand image Remarks

Enter zero (0) or infinite if you do not want the system to display a vertical grid.

Expand image See Also

Reference

HorzGrid Property


Visible Property

Visible Property

Sets whether to display the form or control.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Menu items

  • Option buttons

  • Pages

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Property Value

Yes (true on pages) if you want the form or control to be visible; otherwise, No (false on pages). The default is Yes (true on pages).

Expand image Remarks

Because this property also applies to containers, such as forms and subforms, if the Visible property for the container is set to No, then controls on the container are also not displayed, even if the Visible property is set to Yes.

When this property is used to hide FlowFields on tabular forms, the FlowField is no longer calculated, which can improve performance. However, you might have some code on the form that uses the information in this FlowField, which will not work properly if the FlowField is invisible and not calculated.

The setting of this property can be changed dynamically by using the VISIBLE Function (Control, Form).

Using the Visible Property on RoleTailored Client Pages

On pages, you use the Visible property to show or hide groups, parts, fields and action controls. You can show or hide a control statically by setting the property to true or false, or dynamically by using a boolean variable. Using a variable requires the following:

  • The IncludeInDataSet Property property of the variable must be set to Yes.

  • For field and action controls, the variable must be resolved by the OnInit Trigger or OnOpenPage Trigger.

Expand image See Also

Reference

VISIBLE Function (Control, Form)


Width Property

Width Property

Sets the width of the form or control. Width is displayed in increments of 1/100 of a millimeter.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

Typically, you will click the form or control to select it and then use the mouse to size it. You can also enter an exact measurement.

If you use the wizard, the form and controls are sized for you. You can change the width as necessary.

For forms, changing the width here has no effect on any subforms. You can change the setting of this property dynamically by using the WIDTH Function (Control, Form) function.

For controls, the width specifies the width of the column. Static controls in the heading inherit the width from the column control.

The Width property is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

Height Property
HorzGrid Property
VertGrid Property


Width Property (Dataport field)

Width Property (Dataport field)
See Also
CollapseAll image

Sets the width of a field in a data item of a dataport. Sets the integer value of Width to the number of characters in the field.

Expand image Applies To

Fields (in dataports)

Expand image Remarks

The setting of this property is only used if FileFormat Property is Fixed. If it is, StartPos Property and Width are used to define fields when records are imported or exported.

Expand image See Also

Reference

FileFormat Property
StartPos Property


WithEvents Property

WithEvents Property

Sets whether you want C/SIDE to receive events from a component that it controls. A component can be an automation server or a custom control (OCX).

Expand image Applies To

Global variables of the type Automation Data Type.

Expand image Remarks

When you declare a global variable of the type Automation, you can specify whether you want to receive events. When you set the WithEvents property for the variable to Yes, this automatically generates AL triggers for the events that the component provides. An AL trigger name consists of the name of the automation variable followed by "::<Event name>."

Expand image See Also

Reference

Automation Data Type


XMLVersionNo Property

XMLVersionNo Property

Set which version of XML the XML document conforms to. Two options are available: 1.0 (the default) and 1.1.

Expand image Applies To

XMLports

Expand image Remarks

The XML version number is inserted into the XML document as the XML declaration, for example, <?xml version="1.0"?>.

Expand image See Also

Concepts

Properties


XPos Property

XPos Property

Sets the horizontal position of the form or control. The position is shown in increments of 1/100 of a millimeter.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

This property is updated when you insert a new object or drag a selected object to a new position. You can also enter an exact position manually in the Properties window.

If you use the wizard, the form and controls are positioned for you. You can change the position as necessary.

You can change the setting of this property dynamically by using the XPOS Function (Control, Form).

For forms, the default position is centered.

For controls, you can also use the Align options on the Format menu to quickly align several controls.

If this control is contained inside a table box, the setting is ignored for this control.

The XPos property is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

YPos Property
AutoPosition Property


YPos Property

YPos Property

Sets the vertical position of the form or control. The position is shown in increments of 1/100 of a millimeter.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Forms

  • Frames

  • Images

  • Indicators

  • Labels

  • Matrix boxes

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Shapes

  • Subforms

  • Tab controls

  • Table boxes

  • Text boxes

Expand image Remarks

This property is updated when you insert a new object or drag a selected object to a new position. You can also enter an exact position manually in the Properties window. If you use the wizard, the form and controls are automatically positioned. You can change the position as necessary.

You can change the setting of this property dynamically by using the YPOS Function (Control, Form).

For forms, the default position is centered.

You can also use the Align options on the Format menu to quickly align several controls.

If this control is contained in a table box, the setting for this control is ignored.

The YPos property is not supported in the RoleTailored client. The size and position of controls and pages are determined automatically, depending on the display device used.

Expand image See Also

Reference

XPos Property
YPOS Function (Control, Form)


Triggers

Triggers

Triggers are available for the different objects in Microsoft Dynamics NAV 2009 as described in the following sections:

  • Codeunit Triggers

  • Dataport Triggers

  • Form Control Triggers

  • Form Triggers

  • Page and Action Triggers

  • Report, Section, and Data Item Triggers

  • Table and Field Triggers

  • XMLport Triggers

See Also

Concepts

C/AL Functions
Properties
Information


Form Control Triggers

Form Control Triggers

Controls have a varying number of triggers depending on the type of control. Static controls and container controls have no triggers, while text boxes have a full range of triggers. Other data controls and data container controls have a subset of the possible triggers. Controls that can be clicked such as command buttons, menu items, and check boxes have a special trigger.

C/SIDE Control Triggers

The following table outlines the full range of triggers. The rightmost column indicates the controls that the trigger applies to.

Control trigger | Executed | Controls
OnActivate Trigger | The control is activated. | Command button Menu button Check box Option button Text box Picture box Indicator Subform
OnDeactivate Trigger | The control is deactivated | Command button Menu button Check box Option button Text box Picture box Indicator Subform
OnFormat Trigger | The control is about to be updated. | Text box
OnBeforeInput Trigger | The control is selected for input and before any input is entered. | Text box
OnInputChange Trigger | The user is entering data. This trigger is repeatedly executed, after each keystroke. | Text box
OnAfterInput Trigger | The user finishes input. | Text box
OnPush Trigger | The control is pushed. | Command button Check box Option button Picture box Indicator Menu item
OnValidate (Controls) Trigger | The control loses focus. | Check box Option button Text box Picture box Indicator
OnAfterValidate Trigger | The value entered has been validated. | Check box Option button Text box Picture box Indicator
OnLookup (Controls) Trigger | The user requests a lookup (by clicking a lookup button or by pressing F6). | Text box
OnDrillDown Trigger | The user requests a drill-down (by clicking a drill-down button or by pressing SHIFT+F6). | Text box
OnAssistEdit Trigger | The user requests assist-edit (by clicking an assistedit button or by pressing_SHIFT+F2). | Text box
OnActivate Trigger | The control is activated. | Command button Menu button Check box Option button Text box Picture box Indicator Subform
OnDeactivate Trigger | The control is deactivated | Command button Menu button Check box Option button Text box Picture box Indicator Subform
OnFormat Trigger | The control is about to be updated. | Text box
OnBeforeInput Trigger | The control is selected for input and before any input is entered. | Text box
OnInputChange Trigger | The user is entering data. This trigger is repeatedly executed, after each keystroke. | Text box

OnValidate is also a field trigger at the table level. If both the field and control triggers are defined, the OnValidate (Fields) Trigger is executed before the OnValidate (Controls) Trigger (including the system default validation).

OnLookup is also a field trigger at the table level. The flow is different for this trigger. When a lookup is requested, OnLookup (Controls) Trigger is executed if it is defined in the field lookup or system default. If no control lookup trigger is defined, OnLookup (Fields) Trigger (if defined) replaces the system default lookup function.

See Also

Tasks

How to: Define and Modify Form and Control Triggers

Concepts

Form Triggers


OnActivate Trigger

OnActivate Trigger

Executed when the control is activated.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Indicators

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Subforms

  • Text boxes

Expand image Remarks

When you call ACTIVATE Function (Control), the OnDeactivate Trigger trigger is executed for the previous control and the new control is then activated. After the new control is activated, the code in the OnActivate trigger is executed.

If there is an error occurs in the trigger, the form is closed.

You cannot use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnAfterInput Trigger

OnAfterInput Trigger

Executed when the user switches focus from one control to another.

OnAfterInput(TextString)

Parameters

TextString

The exact user entry.

Expand image Applies To

Text boxes

Expand image Remarks

This trigger is executed after the OnInputChange Trigger is executed for the last time and before the OnValidate (Controls) Trigger is executed. If an error occurs in the trigger code, the form is closed.

You cannot use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnAfterValidate Trigger

OnAfterValidate Trigger

Executed after user input is validated.

Expand image Subhead

  • Check boxes

  • Indicators

  • Option buttons

  • Picture boxes

  • Text boxes

Expand image Remarks

Use this trigger if you want to update the form after the user's input is validated.

If there is an error in the trigger code, the form is closed.

You can use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnAssistEdit Trigger

OnAssistEdit Trigger

Executed in place of the AssistEdit Property features that are provided in Microsoft Dynamics NAV.

Expand image Applies To

  • Text boxes on forms

  • Fields on pages

Expand image Remarks

If there is an error in the trigger code, then the form is closed.

You can use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnBeforeInput Trigger

OnBeforeInput Trigger

Use to specify whether the user can edit the control.

Expand image Applies To

Text boxes

Expand image Remarks

This trigger only determines whether the control is editable.

This trigger is executed after OnFormat Trigger and before OnInputChange Trigger.

If there is an error in the C/AL code entered into this trigger, the form is closed.

You cannot use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnDeactivate Trigger

OnDeactivate Trigger

Executed when the control is deactivated.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Indicators

  • Menu buttons

  • Option buttons

  • Picture boxes

  • Subforms

  • Text boxes

Expand image Remarks

When you call the ACTIVATE Function (Control) function, the code in the OnDeactivate trigger is executed before the OnActivate Trigger for the new control.

If there is an error in the trigger code, the form is closed.

You cannot use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnDrillDown Trigger

OnDrillDown Trigger

Overrides the default drill-down behavior defined in the table definition for the FlowField.

Expand image Applies To

  • Text boxes on forms

  • Fields on pages

Expand image Remarks

If there is an error in the trigger code, the drilldown is canceled. You can use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnFormat Trigger

OnFormat Trigger

Determines how user entries are displayed on the screen, including alignment.

OnFormat(TextString)

Parameters

TextString

The default formatting information.

Expand image Applies To

Text boxes

Expand image Remarks

The formatting instructions you enter in this trigger, via C/AL code, affect only what the user sees on the screen. The code you place in this trigger does not affect how data is stored.

This is the first trigger executed when a user highlights a control to enter data; the OnBeforeInput Trigger is the next trigger executed.

This trigger is called after the control is formatted. The TextString parameter contains the default format information.

The form closes if an error occurs in the trigger code. You cannot use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnInputChange Trigger

OnInputChange Trigger

Executes while the user is making entries into a text box.

Expand image Applies To

Text boxes

Expand image Remarks

Use this trigger to check user entries as they are made. This trigger is executed after OnBeforeInput Trigger and continues to execute after each keystroke. After the final keystroke, the OnAfterInput Trigger trigger is executed.

If there is an error in the C/AL code you enter into this trigger, the form closes.

You cannot use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnLookup (Controls) Trigger

OnLookup (Controls) Trigger

Executed in place of the normal lookup features for the current form or page only.

OnLookup(TextString)

Parameters

TextString

Text string entered into the text box and used as the lookup value.

Expand image Applies To

  • Text boxes on forms

  • Fields on pages

Expand image Remarks

There are three lookup options:

  • Default Lookup - The lookup into the table is performed without applying filters or other special parameters.

  • Field Lookup - You can define a lookup trigger on a field that will be used in place of the default lookup. For more information, see OnLookup (Fields) Trigger.

  • Text box Lookup - You can use this trigger to define a lookup based on the value of a text box. This value will be used in place of the default lookup or the field lookup.

For example, for the Customer Code field, a lookup into the Customer table is provided. If you want a lookup into another table or if you want to place a filter on the table before displaying the lookup, use this trigger.

If an error occurs in the trigger code, the lookup is canceled.

You can use this trigger to write to the database.

Note Note

OnLookup is also a field trigger at the table level. The flow is different for this trigger. When a lookup is requested, OnLookup (Controls) Trigger is executed if it is defined in the field lookup or system default. If no control lookup trigger is defined, OnLookup (Fields) Trigger (if defined) replaces the system default lookup function.

Expand image See Also

Concepts

Triggers


OnPush Trigger

OnPush Trigger

Executed when the user clicks the control with the left mouse button.

Expand image Applies To

  • Check boxes

  • Command buttons

  • Images

  • Indicators

  • Labels

  • Menu items

  • Option buttons

  • Picture boxes

  • Shapes

Expand image Remarks

Typically, you use attributes to run a report or open a form when a button is clicked or a box is checked. You can use this trigger to apply a filter before a report is printed or a form is displayed.

This trigger is called after default push action occurs, such as RunObject Property. The PushAction Property is canceled if an error occurs in the trigger code. You can use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnValidate (Controls) Trigger

OnValidate (Controls) Trigger

Executed when the user leaves the control.

Expand image Applies To

  • Check boxes

  • Indicators

  • Option buttons

  • Picture boxes

  • Text boxes

Expand image Remarks

Use this trigger to validate user entries. For example, you can use the OnAfterInput Trigger to change the entry "P" into the first day of the current period and then use this trigger to make sure that day is valid.

This trigger is executed after the OnAfterInput trigger and the default validation for the control. The form is not closed if an error occurs in the trigger code; however, the user input is validated.

OnValidate is also a field trigger at the table level. If both the field and control triggers are defined, the OnValidate (Fields) Trigger is executed before the OnValidate (Controls) Trigger (including the system default validation).

Note Note

You can use this trigger to write to the database. You cannot call the UPDATE function from this trigger.

Expand image See Also

Concepts

Triggers


Form Triggers

Form Triggers

The following triggers apply to forms in C/SIDE.

C/SIDE Form Triggers

The following table lists the form triggers and when they are executed.

Form trigger name | Executed
OnInit Trigger | The form is loaded, but before the controls are available.
OnOpenForm Trigger | The form is initialized (the controls are available).
OnQueryCloseForm Trigger | The form is about to close, but before OnCloseForm Trigger. If this trigger returns false, the form is not closed. The intended use is to ask the user if they really want to close the form.
OnCloseForm Trigger | The form is about to close, and after OnQueryCloseForm Trigger.
OnActivateForm Trigger | The form is activated, that is, when the form becomes the active window.
OnDeactivateForm Trigger | The form is no longer the active window.
OnFindRecord Trigger | The form is opened and a record is retrieved and also when the user chooses to go to the first or the last record.
OnNextRecord Trigger | The system determines how to select the next record, for example after a user presses PAGE DOWN (in a card form).
OnAfterGetRecord Trigger | A record has been retrieved but not yet displayed.
OnAfterGetCurrRecord Trigger | The current record is retrieved. In a table box, OnAfterGetRecord Trigger is called for all the records displayed, while this trigger is called for the current record.
OnBeforePutRecord Trigger | A record is about to be saved.
OnNewRecord Trigger | A new record has been initialized but not yet displayed.
OnInsertRecord Trigger | A new record is about to be inserted in the table.
OnModifyRecord Trigger | A record is about to be modified in the table.
OnDeleteRecord Trigger | A record is about to be deleted from the table.
OnTimer Trigger | After the OnOpenForm Trigger and after the time specified in the TimeInterval property of the form has elapsed.
OnCreateHyperlink Trigger | You create a URL to a form so that you can send it by e-mail or paste it on your desktop.
OnHyperlink Trigger | You click a hyperlink and after the OnInit Trigger is executed.

The preceding table only shows the main function of each trigger.

Note Note

OnInsertRecord Trigger, OnModifyRecord Trigger, and OnDeleteRecord Trigger, correspond to triggers at the table level. If you use triggers at both the form and table level, the triggers at the form level are executed first.

See Also

Tasks

How to: Define and Modify Form and Control Triggers

Concepts

Form Control Triggers
Triggers


OnActivateForm Trigger

OnActivateForm Trigger

Executed after the user activates the form.

Expand image Applies To

Forms

Expand image Remarks

The following example explains how this trigger is used. A user has two forms displayed — Form A and Form B. The user enters data on Form A. When the user activates Form B (typically by clicking on the form), the code in the OnDeactivateForm Trigger for Form A is executed and then the code in this trigger for Form B is executed.

If there is an error in the trigger code, the form is closed.

Expand image See Also

Concepts

Triggers


OnAfterGetCurrRecord Trigger

OnAfterGetCurrRecord Trigger

Executed after the current record is retrieved from the table.

Expand image Applies To

Forms

Expand image Remarks

In a form with a table box, this trigger is only called when the current record in the table box is updated.

If there is an error in the trigger code, the form is closed.

Expand image See Also

Concepts

Triggers


OnAfterGetRecord Trigger

OnAfterGetRecord Trigger

Executed after a record is retrieved from a table but before it is displayed to the user.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

Use this trigger to calculate variables that depend on the current record. In a form with a table box, this trigger is called for each record in the table box, as the records are updated.

If there is an error trigger code, the form or page is closed.

Expand image See Also

Concepts

Triggers


OnBeforePutRecord Trigger

OnBeforePutRecord Trigger

Executed before a record is saved.

Expand image Applies To

Forms

Expand image Remarks

If there is an error in the trigger code, the form is closed.

Expand image See Also

Concepts

Triggers


OnCloseForm Trigger

OnCloseForm Trigger

Executed immediately after a form is removed from the screen, but before it has been closed.

Expand image Applies To

Forms

Expand image Remarks

This trigger is called by a user action, such as when the user clicks Close or when the CurrForm.CLOSE Function (Form, Table) function is called. Before this trigger is executed, the OnQueryCloseForm Trigger trigger is executed.

If there is an error in the trigger code, the form is closed.

You can write to the database from within this trigger.

Expand image See Also

Concepts

Triggers


OnCreateHyperlink Trigger

OnCreateHyperlink Trigger
See Also Example
CollapseAll image

Executed after the user creates a URL to a form or a report.

OnCreateHyperlink(URL)

Parameters

URL

Data type — text or code.

Expand image Applies To

  • Forms

  • Reports

Expand image Remarks

A user can create a URL for the active form or report by clicking for example:

  • File, Send, Link by E-Mail

  • File, Send, Copy Link

  • File, Send, Shortcut to Desktop

C/SIDE fills in the URL parameter with the default URL string to the form. You can change the default value by changing the contents of the string.

The OnCreateHyperlink trigger is not supported on client report definition (RDLC) report layouts.

Expand image Example

The following is an example of a URL string.
CopyCode image Copy Code
DynamicsNAV://client/run?database=c:\database.fdb&company=dot.com&target=form991&forcenewinstance=yes

Expand image See Also

Concepts

Triggers


OnDeactivateForm Trigger

OnDeactivateForm Trigger

Executed after the user places focus on another form, but before it deactivates this form.

Expand image Applies To

Forms

Expand image Remarks

For example, assume the user has two forms displayed, Form A and Form B, and the user is entering data on Form A. When the user activates Form B, typically by clicking on the form, the the code in this trigger is executed for Form A and then the OnActivateForm Trigger is executed for Form B.

If there is an error in the trigger code, the form is closed.

Expand image See Also

Concepts

Triggers


OnDeleteRecord Trigger

OnDeleteRecord Trigger

Executed before a record is deleted from the table.

[Ok]:= OnDeleteRecord

Expand image Return Value

Ok

(Boolean) If true, the record is deleted. If false, the record is not deleted. This value is checked after each function call.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

The action is canceled but the form is not closed if an error occurs in the trigger code. You can use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnFindRecord Trigger

OnFindRecord Trigger

Overrides the default form behavior and enables you to specify which record you want to display when the form opens.

[Ok]:= OnFindRecord(Which)

Parameters

Which

Text or code value with the following options:

Expand image Return Value

Ok

(Boolean) Indicates whether the specified record was found.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

By default, opened forms display the last record shown when the user exited the form. Use this trigger to override the default behavior and display the first record, last record, or a specific record as defined in the Rec variable.

Expand image See Also

Concepts

Triggers


OnHyperlink Trigger

OnHyperlink Trigger

Executed after the OnInit Trigger executes for a form or after the OnInitReport Trigger executes for a report.

Object.OnHyperlink(URL)

Parameters

URL

Data type: text or code

The trigger executes a URL string.

Expand image Applies To

  • Forms

  • Reports

Expand image Remarks

A URL can be created with a call to the OnCreateHyperlink Trigger.

The OnHyperlink trigger is not supported on client report definition (RDLC) report layouts.

Expand image See Also

Concepts

Triggers


OnInit Trigger

OnInit Trigger

Initializes the user-defined variables on the form or page.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

The C/AL code in this trigger is executed immediately after the variables are cleared and the form or page is loaded. This trigger cannot be used to access the controls on the form or page. You can change properties that are dynamic, including those properties that can only be changed when the form or page is opened.

After this trigger is executed, the OnOpenForm Trigger for forms or the OnOpenPage Trigger for pages is called. If an error occurs in the trigger code, then the form or page is closed.

Differences Between the Classic Client and RoleTailored Client

In the RoleTailored client, if you set filters, keys, sort order, or other settings that affect a table view in the OnInit trigger, then the settings are overwritten by the OnOpenForm trigger. Instead of setting these in the OnInit trigger, do one of the following tasks:

  • Specify the settings on the table view of the page instead of in a trigger.

  • Specify the settings in the OnOpenForm trigger.

Expand image See Also

Concepts

Triggers


OnInsertRecord Trigger

OnInsertRecord Trigger

Executes before a new record is inserted into the table.

[Ok]:= OnInsertRecord(BelowxRec)

Expand image Return Value

BelowxRec

(Boolean) This return value indicates whether the new record was inserted after the last record in the table (xRec) or not. If false, the record was inserted between an existing record and the last record. If true, the record was inserted below the last record in the table (xRec).

Ok

(Boolean) Indicates whether a new record should be inserted. The return value is checked after each function call. If true, the record is inserted. If false, the record is not inserted.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

If an error occurs in the trigger code, the action is canceled but the form is not closed.

Expand image See Also

Concepts

Triggers


OnModifyRecord Trigger

OnModifyRecord Trigger

Executes before a record is modified in the table.

[Ok]:= OnModifyRecord

Expand image Return Value

Ok

(Boolean) Indicates whether a record should be modified. The return value is checked after each function call. If true, the record is modified (default). If false, the record is not modified.

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

If an error occurs in the trigger code, the action is canceled, but the form is not closed.

You can write to the database using this trigger.

Expand image See Also

Concepts

Triggers


OnNextRecord Trigger

OnNextRecord Trigger

Determines the next record to be displayed.

[ActualSteps]:=OnNextRecord(Steps)

Parameters

Steps

(Integer) The number of records stepped through before displaying another record. A negative value indicates steps backwards.

Expand image Return Value

ActualSteps

(Integer) This return value contains the actual number of steps or records cycled through. The default value is zero (0).

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

This trigger is executed in place of the default next record behavior.

If an error occurs in the trigger code, the form is closed.

Expand image See Also

Concepts

Triggers


OnNewRecord Trigger

OnNewRecord Trigger

Executes after a new record is initialized, but before users can make entries.

OnNewRecord(BelowxRec)

Expand image Return Value

BelowxRec

(Boolean) This return value indicates whether the new record was inserted after the last record in the table (xRec). If false, the record was inserted between an existing record and the last record. If true, the record was inserted below the last record in the table (xRec).

Expand image Applies To

  • Forms

  • Pages

Expand image Remarks

Use this trigger to initialize a new record or other variables on the form.

If an error occurs in the trigger code, the form is closed.

Expand image See Also

Concepts

Triggers


OnOpenForm Trigger

OnOpenForm Trigger

Executes after a form is initialized and run.

Expand image Applies To

Forms

Expand image Remarks

Use this trigger to change dynamic properties, including those which can only be changed when the form is opened, such as the MaximizedOnOpen Property.

This trigger executes after the OnInit Trigger.

If an error occurs in the trigger code, the form closes. You can write to the database from using this trigger.

If you use the LOCKTABLE function in this trigger, the table lock will be released as soon as the trigger executes and not when you close the form.

Expand image See Also

Concepts

Triggers


OnQueryCloseForm Trigger

OnQueryCloseForm Trigger

Executed immediately before the form closes.

[Ok]:= OnQueryCloseForm

Expand image Property Value/Return Value

Ok

(Boolean) Indicates whether the form should be closed. This value is checked after each function call.

Expand image Applies to

Forms

Expand image Remarks

If neither the form nor any child form returns FALSE in this trigger, the OnCloseForm Trigger trigger is called for all child forms and then for the form itself (the parent form).

The close action is canceled if an error occurs in the trigger code, and the form is not closed. You can use this trigger to write to the database.

Expand image See Also

Concepts

Triggers


OnTimer Trigger

OnTimer Trigger

Executes the trigger once the OnOpenForm Trigger executes and after the time specified in the TimerInterval Property has elapsed.

Expand image Applies To

Forms

Expand image Remarks

The frequency with which the OnTimer trigger executes is determined by the value of the TimerInterval property.

Caution note Caution

This trigger can adversely impact system performance if large demands on system resources are made.

Expand image See Also

Concepts

Triggers


Dataport Triggers

Dataport Triggers

The following triggers apply to dataports in C/SIDE.

C/SIDE Dataport Triggers

Dataport trigger | Executed
OnAfterExportRecord Trigger | Executed after a record has been exported.
OnAfterFormatField Trigger | Executed after the value of a field is formatted.
OnAfterImportRecord Trigger | Executed after a record has been read from the external (import) file.
OnBeforeEvaluateField Trigger | Executed after the field has been imported from the external (import) file.
OnBeforeExportRecord Trigger | Executed before a record is exported.
OnBeforeImportRecord Trigger | Executed before the next record is read from the external (import) file.
OnInitDataPort Trigger | Executes when the dataport is loaded.
OnPostDataPort Trigger | Executed after a dataport is run.
OnPreDataPort Trigger | Executed before a dataport is run.

See Also

Tasks

How to: Define or Modify Table or Field Triggers

Concepts

Creating Dataports
Designing Dataports
XMLport Triggers


OnAfterExportRecord Trigger

OnAfterExportRecord Trigger

Executed after a record has been exported.

Expand image Applies To

Dataports

Expand image Remarks

This trigger will only be executed when Import Property equals No.

You can use this trigger to perform operations on the external (export) file before the next record is exported. For example, use this trigger when moving the file pointer with SEEK Function (File) to insert the next record at a specific location in the file.

Expand image See Also

Concepts

Triggers


OnAfterFormatField Trigger

OnAfterFormatField Trigger

Executed after the value of a field is formatted.

Expand image Applies To

Dataports

Expand image Remarks

This trigger is only executed when Import Property equals No.

The trigger is executed after the field has been formatted, but before it is written to the file. The Text parameter contains the formatted value of the field, and you can do any processing that is necessary before actually writing the field to the file.

Expand image See Also

Concepts

Triggers


OnAfterImportRecord Trigger

OnAfterImportRecord Trigger

Executed after a record has been read from the external (import) file.

Expand image Applies To

Dataports

Expand image Remarks

This trigger is only executed when Import Property equals Yes.

The trigger is executed after the record is read from the table, but before it is inserted into the table. You can use this trigger to perform postprocessing that is required before the record is inserted. You can use the SKIP Function (Dataport, Report, XMLport) to skip inserting this record or stop the processing of the data item by using the BREAK Function (Dataport, Report, XMLport).

If you add code to this trigger that updates a field, you must ensure that the field has been added to the list of dataport fields. For more information about dataport fields, see Designing Dataports.

Expand image See Also

Concepts

Triggers


OnBeforeEvaluateField Trigger

OnBeforeEvaluateField Trigger

Executed after the field has been imported from the external (import) file.

Expand image Applies To

Dataports

Expand image Remarks

This trigger will only be executed when Import Property equals Yes.

The trigger is executed after the field has been imported from the file, but before the value has been evaluated and validated. The Text parameter contains the imported field in text format, and you can perform any processing that is necessary before actually evaluating the field.

Expand image See Also

Concepts

Triggers


OnBeforeExportRecord Trigger

OnBeforeExportRecord Trigger

Executed before a record is exported.

Expand image Applies To

Dataports

Expand image Remarks

This trigger will only be executed when Import Property equals No.

Before this trigger executes, the next record of the data item is retrieved and any FlowFields are calculated. You can use this trigger to perform any postprocessing required before the record is exported. You can use the SKIP Function (Dataport, Report, XMLport) to skip exporting this record or stop the processing of the data item altogether by using the BREAK Function (Dataport, Report, XMLport).

Expand image See Also

Concepts

Triggers


OnBeforeImportRecord Trigger

OnBeforeImportRecord Trigger

Executed before the next record is read from the external (import) file.

Expand image Applies To

Dataports

Expand image Remarks

This trigger will only be executed when Import Property equals Yes.

You can use this trigger to perform operations on the external (import) file before the next record is imported - for example, moving the file pointer with SEEK Function (File) to read a specific record next.

Expand image See Also

Concepts

Triggers


OnInitDataPort Trigger

OnInitDataPort Trigger

Executes when the dataport is loaded.

Expand image Applies To

Dataports

Expand image Remarks

This trigger executes before the request form is run and before any table views or filters are set.

Expand image See Also

Concepts

Triggers


OnPostDataPort Trigger

OnPostDataPort Trigger

Executed after a dataport is run.

Expand image Applies To

Dataports

Expand image Remarks

This trigger is executed after all data items are processed.

Expand image See Also

Concepts

Triggers


OnPreDataPort Trigger

OnPreDataPort Trigger

Executed before a dataport is run.

Expand image Applies To

Dataports

Expand image Remarks

This trigger executes after the request form is run. The table views and filters for the data items in the dataport are set when the trigger is executed.

Expand image See Also

Concepts

Triggers


Report, Section, and Data Item Triggers

Report, Section, and Data Item Triggers

In reports, triggers are typically used to perform calculations and to control whether to output sections. Triggers allow you to control how data is selected and retrieved in a more complex and effective way than you can achieve by using properties.

Report Triggers

The following table lists triggers that apply to the report itself.

Trigger | Executed
OnInitReport Trigger | When the report is loaded.
OnPreReport Trigger | Before the report is run, but after the RequestForm has been run.
OnPostReport Trigger | After the report has run, but not if the report was stopped manually or by the Break function.
OnCreateHyperlink Trigger | After the user creates a URL to a form or a report.
OnHyperlink Trigger | After the OnInitReport Trigger is executed for a report. The trigger executes a URL string.

Data Item Triggers

The following table lists triggers that apply to each data item on the report.

Trigger | Executed
OnPreDataItem Trigger | Before the data item is processed, but after the associated variable has been initialized.
OnAfterGetRecord (Data Items) Trigger | When a record has been retrieved from the table.
OnPostDataItem Trigger | When the data item has been iterated for the last time.

Section Triggers

The following table lists triggers that apply to each of the sections of a data item.

Triggers | Executed
OnPreSection Trigger | Before processing a section.
OnPostSection Trigger | After processing a section but before printing it.

See Also

Tasks

How to: Define and Modify Form and Control Triggers

Concepts

Triggers


OnAfterGetRecord (Data Items) Trigger

OnAfterGetRecord (Data Items) Trigger

Executed each time a record is retrieved from the data item.

Expand image Applies To

Data items

Expand image Remarks

Use this trigger to perform any processing that is needed, based on the values in the fields of the individual records of a data item.

If the record contains FlowFields, you can put CALCFIELDS Function (Record) statements in this trigger to have them calculated. While it is normally easier to use the CalcFields Property to have it done automatically, there are situations where you have to use this trigger to perform the calculation explicitly. For example, if you apply FlowFilters based on the context of the report or the dataport to the FlowFields inside this trigger, you need to recalculate the FlowFields after you have applied the FlowFilters.

Another example is when you need to retrieve information from a table that is external to the report or dataport. This is the situation when the records of a data item contain fields that are foreign keys (that is, fields that are primary keys in other tables), and you want to extract further information from the related tables. For example, in a report, the records in a data item might contain a field with a Vendor code, while you want to print the full name and address of the vendor. You use this trigger to retrieve the information in order to print it in your report.

Expand image See Also

Concepts

Triggers


OnInitReport Trigger

OnInitReport Trigger

Executes when the report is loaded.

Expand image Applies To

Reports

Expand image Remarks

This trigger is executed before the request form is run and before any table views or filters are set. This could be used to initialize global variables.

Expand image See Also

Concepts

Triggers


OnPreReport Trigger

OnPreReport Trigger

Executed before a report is run.

Expand image Applies To

Reports

Expand image Remarks

This trigger executes after the request form is run. The table views and filters for the report data items are set while this trigger is executed. As this trigger is executed after the request form is processed, you have access to any filters the user has set. If you want to print the settings of these filters in the report, you can retrieve them using the following text string.

CopyCode image Copy Code
ReportFilter := SomeRecord.GETFILTERS;

Use the ReportFilter text string as the source expression for a control in a section of the report.

Expand image See Also

Reference

GETFILTERS Function (Record)


OnPostReport Trigger

OnPostReport Trigger

Executes after a report is run.

Expand image Applies To

Reports

Expand image Remarks

This trigger is executed after all data items are processed. The trigger is not run if the report was stopped manually or by using the QUIT function before processing had concluded.

Because this trigger is executed after the report is processed, you can use it to inform users about the result of the report run. For example, if some records could not be processed, you could inform the user of this using the following code in this trigger.

CopyCode image Copy Code
IF ProblemsInReport THEN
MESSAGE(Text000, NumberOfErrors);

Create the following text constant in the C/AL Globals window.

Text constant | ENU value
Text000 | '%1 records were not processed'

Because this trigger is executed before the End Write Transaction, you can also give the user the opportunity to roll back changes to the database by leaving the report with the QUIT Function (Dataport, Report, XMLport).

Expand image See Also

Reference

QUIT Function (Dataport, Report, XMLport)


OnPreSection Trigger

OnPreSection Trigger
See Also Example
CollapseAll image

Executed before a section is processed.

Expand image Applies To

Sections

Expand image Remarks

This trigger executes before the space required for the output section is calculated. Only use this trigger to perform visual processing of the report — not data processing. A key use of this trigger is as a means of determining whether to output a section based on the value of one or more fields or variables.

Note Important

Section triggers are not supported on client report definition (RDLC) report layouts.

Expand image Example

You can use this trigger to test the value of a specific field and then take an action based on that value. For example, you might want print the record to a report only when the amount does not equal zero.
CopyCode image Copy Code
CurrReport.SHOWOUTPUT(Amount <> 0);

Expand image See Also

Concepts

Triggers


OnPostSection Trigger

OnPostSection Trigger

Executed after a section has been processed.

Expand image Applies To

Sections

Expand image Remarks

This trigger executes after the section has been processed, but before it is actually printed.

This trigger should only be used to perform processing that has to do with the visual output of the report, not processing of data.

In this trigger the actual page number is valid, because if the section could not be printed on the current page, the necessary page break will already have been inserted by the time this trigger is executed.

Note Important

Section triggers are not supported on client report definition (RDLC) report layouts.

Expand image See Also

Concepts

Triggers


OnPreDataItem Trigger

OnPreDataItem Trigger

Executed before a data item is processed.

Expand image Applies To

Data items

Expand image Remarks

This trigger is executed before a data item is processed, but after the associated variable is initialized and table views and filters are set.

You can use this trigger to add additional filtering beyond what is established by the DataItemLink Property or DataItemTableView Property. For example, use this trigger if you need to filter an indented data item based on the result of a calculation. Use the SETRANGE Function (Record) or SETFILTER Function (Record) function to add extra delimiters.

If you need to create totals for a variable (instead of a field), you can add a statement such as the following.

CopyCode image Copy Code
CurrReport.CREATETOTALS(Variable);

Adding this statement to the trigger maintains totals in the same way that field totals are maintained by using the TotalFields Property.

Expand image See Also

Reference

DataItemLink Property
DataItemTableView Property
SETRANGE Function (Record)
SETFILTER Function (Record)


OnPostDataItem Trigger

OnPostDataItem Trigger

Executed after a data item is processed.

Expand image Applies To

Data items

Expand image Remarks

This trigger executes after the last record in the data item is processed but before the OnPostReport Trigger or the OnPostDataPort Trigger is executed, if it is the last data item of the report or dataport.

Use this trigger to perform any cleanup or post processing needed after a data item is processed. For example, if you create a non-printing report where records are updated, you can update all the records with the modification date like this.

CopyCode image Copy Code
MODIFYALL("Modification Date",TODAY);

Expand image See Also

Reference

OnPostReport Trigger
OnPostDataPort Trigger


Table and Field Triggers

Table and Field Triggers

C/SIDE recognizes certain actions that happen to a table when you use it, for example, that you insert or modify data. In response, you can set up Microsoft Dynamics NAV to execute C/AL code defined in a trigger. Triggers are predefined functions that are executed when certain actions happen. The bodies of these functions are initially empty and must be defined by the developer. Defining C/AL code in triggers allows you to change the default behavior of Microsoft Dynamics NAV.

The triggers in a C/SIDE table can be divided into two categories:

  • Table triggers

  • Field triggers

Tables have the following triggers.

Table trigger | Executes when
OnInsert Trigger | A new record is inserted into the table.
OnModify Trigger | A record in the table is modified.
OnDelete Trigger | A record in the table is deleted.
OnRename Trigger | A record is modified in a primary key field.

Fields have the following triggers.

Field trigger | Executes when
OnValidate (Fields) Trigger | Data is entered in a field or when the VALIDATE Function (Record) is executed.
OnLookup (Fields) Trigger | Lookup is activated.

See Also

Tasks

How to: Define or Modify Table or Field Triggers


OnDelete Trigger

OnDelete Trigger

Executed when a user tries to delete a record.

Expand image Applies To

Tables

Expand image Remarks

This trigger executes before the default delete behavior. The record is not deleted if an error occurs in the trigger code.

Expand image See Also

Concepts

Triggers


OnInsert Trigger

OnInsert Trigger

Executes when a user inserts a new record into the table.

Expand image Applies To

Tables

Expand image Remarks

This trigger executes before default insert behavior occurs. The new record is not inserted if an error occurs in the trigger code.

In tables where records are entered in forms that have the DelayedInsert Property set to Yes, we recommend that you write any code that is in an OnInsert trigger so that it will always succeed. For example, this applies to journal lines.

Expand image See Also

Reference

PasteIsValid Property

Concepts

Triggers


OnModify Trigger

OnModify Trigger

Executes when a user modifies an existing record in a table.

Expand image Applies To

Tables

Expand image Remarks

This trigger executes before the default modify behavior is executed. If an error occurs in the trigger code, the record changes are canceled.

We recommend that you do not include code that can stop the user from recording a change in the OnModify trigger on a table. For example, do not include code for displaying error messages. If a user has previously changed the contents of some fields in a record, then these changes must always be accepted by the system.

Expand image See Also

Concepts

Triggers


OnRename Trigger

OnRename Trigger

Executed when a user tries to rename a record.

Expand image Applies to

Tables

Expand image Remarks

When you rename a record in one location, it is updated in all other locations. The OnRename trigger executes before the rename occurs. The record is not renamed if an error occurs in the trigger code.

Expand image See Also

Concepts

Triggers


OnLookup (Fields) Trigger

OnLookup (Fields) Trigger

Causes the system to display a lookup form.

Expand image Applies To

Fields

Expand image Remarks

There are three lookup options:

  1. Default Lookup - The lookup into the table is performed without applying filters or other special parameters.

  2. Field Lookup - You can use this trigger to define a field lookup that will be used in place of the default lookup.

  3. Text box Lookup - You can use the OnLookup (Controls) Trigger to define a lookup based on the value of a text box. This value will be used in place of the default lookup or the field lookup.

When using this trigger, follow this approach:

  • Use the field value to determine what filters or other parameters to apply.

  • Run the lookup form as a modal form.

  • Transfer the value the user selects back to the field when the user clicks OK.

If an error occurs in the trigger code, the lookup form is closed.

Expand image See Also

Reference

OnLookup (Controls) Trigger


OnValidate (Fields) Trigger

OnValidate (Fields) Trigger

Executed when user input is validated.

Expand image Applies To

Fields

Expand image Remarks

This trigger is executed after the default validation behavior. An error message displays if an error occurs in the trigger code. In case of an error, the user entry is not written to the database.

Differences Between the Classic Client and RoleTailored Client

We recommend that you carefully consider the code that you use in OnValidate triggers. In the Classic client, if a user encounters a validation error the user will not be able to enter input in any other field. In some cases, the user is not able to fix the validation error and must close and re-open the form to enter the correct values. For example, Table 225, Post Code, has an OnValidate trigger for the City field that checks whether the Code field is empty. On Form 367, Post Codes, the Code field is placed before the City field. However, if a user chooses to enter the city before entering the postal code, a validation error occurs and the user cannot enter input in the Code field to fix the validation error. The user must close Form 367. When the user closes the form, the data that was entered is not written to the database because of the error. The user can re-open Form 367 and enter the postal code before entering the city.

In the RoleTailored client, if a user encounters a validation error this problem does not halt the user because the user can enter input in other fields. For example, if a user uses Page 367, Post Codes, and enters a value in the City field before entering a postal code value in the Code field, then a validation error occurs. In the RoleTailored client, the user can then enter a postal code value in the Code field. When the OnValidate trigger runs again, the validation error does not occur. When the user closes the page, the data is written to the database.

Another example is Form 42, Sales Order. In a sales order line, if a user selects Item in the Type field and then in the No. field the user types one of the resources instead of one of the items, the following validation error occurs:

Item No. ' <resource entered> ' does not exist.

One way to fix the validation error is to change the Type field to Resource instead of Item. However, in the Classic client you cannot enter input in any field other than the No. field after the validation error occurs. To fix this error, you must instead remove the input from the No. field and then you can change the input in the Type field. In the RoleTailored client, after you get the validation error, to fix the error you can change the Type field to Resource instead of Item.

Expand image See Also

Concepts

Triggers


XMLport Triggers

XMLport Triggers

The following triggers apply to XMLports in C/SIDE.

C/SIDE XMLport Triggers

XMLport trigger | Executed
OnAfterAssignField Trigger | Executed after a field has been assigned a value and before it is validated and imported. This trigger is only used to import data.
OnAfterAssignVariable Trigger | Executed after the value defined in the XML document is assigned to the text variable. This trigger is only used to import data.
OnAfterGetField Trigger | Executed after a field is passed to the XML document. This trigger is only used to export data.
OnAfterGetRecord (XMLports) Trigger | Executed after a record is retrieved from a table and before it is exported to the XML document. This trigger is only used to export data.
OnAfterInitRecord Trigger | Executed after a record is loaded. This trigger is only used to import data.
OnAfterInsertRecord Trigger | Executed after a record has been inserted into a database table. This trigger is only used to import data.
OnBeforeInsertRecord Trigger | Executed after a record has been loaded and before it is inserted into a database table. This trigger is only used to import data.
OnBeforePassField Trigger | Executed before a field is passed to the XML document. This trigger is only used to export data.
OnBeforePassVariable Trigger | Executed after the source expression has been formatted into a text variable and before the text variable is passed to the XML document. This trigger is only used to export data.
OnInitXMLport Trigger | Executes when the XMLport is loaded and before any table views and filters are set.
OnPreXMLport Trigger | Executed after the table views and filters are set and before the XMLport is run.
OnPostXMLport Trigger | Executes after the XMLport is run.
OnPreXMLItem Trigger | Executed after the table is initialized and before you start exporting data to an XML object. This trigger only applies to XMLport elements that have a source type of Table. This trigger is only used to export data.

See Also

Tasks

How to: Define or Modify Table or Field Triggers


OnAfterAssignField Trigger

OnAfterAssignField Trigger

Executed after a field has been assigned a value and before it is validated and imported.

Expand image Applies To

XMLports

Expand image Remarks

This trigger is only used to import data. It gives you access to the values in the imported record and is typically used to manipulate data that is being imported.

Expand image See Also

Concepts

Triggers


OnAfterAssignVariable Trigger

OnAfterAssignVariable Trigger

Executed after the value defined in the XML document is assigned to the text variable.

Expand image Applies to

XMLports

Expand image Remarks

This trigger is only used to import data and gives you access to the imported value in text format.

Expand image See Also

Concepts

Triggers


OnAfterGetField Trigger

OnAfterGetField Trigger

Executed after a field is passed to the XML document.

Expand image Applies To

XMLports

Expand image Remarks

This trigger is only used to export data. This trigger gives you access to the field value in the record just before it is exported and is typically used to manipulate the field.

Expand image See Also

Concepts

Triggers


OnAfterGetRecord (XMLports) Trigger

OnAfterGetRecord (XMLports) Trigger

Executed after a record is retrieved from a table and before it is exported to the XML document.

Expand image Applies To

XMLports

Expand image Remarks

This trigger is only used to export data. It is typically used to manipulate the fields that are being exported from the table and to calculate the variables that depend on the record.

Expand image See Also

Concepts

Triggers


OnAfterInitRecord Trigger

OnAfterInitRecord Trigger

Executed after a record is loaded.

Expand image Applies To

XMLports

Expand image Remarks

This trigger is only used to import data. It is typically used to set up the preconditions for the record before it is inserted into the database table.

Expand image See Also

Concepts

Triggers


OnAfterInsertRecord Trigger

OnAfterInsertRecord Trigger

Executed after a record has been inserted into a database table.

Expand image Applies To

XMLports.

Expand image Remarks

This trigger is only used to import data and can be used to move data from temporary tables to real tables.

Expand image See Also

Concepts

Triggers


OnBeforeInsertRecord Trigger

OnBeforeInsertRecord Trigger

Executed after a record has been loaded and before it is inserted into a database table.

Expand image Applies To

XMLports

Expand image Remarks

This trigger is only used to import data. It is typically used for manipulation of the record before it is inserted into the database table.

Expand image See Also

Concepts

Triggers


OnBeforePassField Trigger

OnBeforePassField Trigger

Executed before a field is passed to the XML document.

Expand image Applies To

XMLports

Expand image Remarks

This trigger is only used to export data. This trigger gives you access to the field value in the record just before it is exported and is typically used to manipulate the field.

Expand image See Also

Concepts

Triggers


OnBeforePassVariable Trigger

OnBeforePassVariable Trigger

Executed after the source expression has been formatted into a text variable and before the text variable is passed to the XML document.

Expand image Applies To

XMLports

Expand image Remarks

This trigger is only used to export data and is typically used to manipulate the text variable.

Expand image See Also

Concepts

Triggers


OnInitXMLport Trigger

OnInitXMLport Trigger

Executes when the XMLport is loaded and before any table views and filters are set.

Expand image Applies To

XMLports

Expand image See Also

Concepts

Triggers


OnPreXMLport Trigger

OnPreXMLport Trigger

Executed after the table views and filters are set and before the XMLport is run.

Expand image Applies To

XMLports

Expand image See Also

Concepts

Triggers


OnPostXMLport Trigger

OnPostXMLport Trigger

Executes after the XMLPort is run.

Expand image Applies To

XMLPorts

Expand image Remarks

This trigger executes after all data items are processed.

Expand image See Also

Concepts

Triggers


OnPreXMLItem Trigger

OnPreXMLItem Trigger

Executed after the table is initialized and before you start exporting data to an XML object. This trigger only applies to XMLPort elements that have a source type of Table.

Expand image Applies To

XMLports

Expand image Remarks

This trigger is only used to export data. It is typically used to set filters on the data and to initialize variables before finding the first record.

Expand image See Also

Concepts

Triggers


Page and Action Triggers

Page and Action Triggers

Page triggers are similar in operation and use to form triggers. Page triggers allow you to use C/AL code to control the behavior of the system as a result of an event on the page, such as a page opening or a field changing its value. You typically use page triggers for advanced validation and logic.

Page triggers can be divided into three categories:

  • General page triggers that apply to the entire page

  • Field page triggers that apply to a field control on a page

  • Action triggers that apply to an action on a page.

General Triggers

The following table lists triggers that apply to the entire page.

Page trigger name | Executed
OnInit Trigger | When the page is loaded, but before the controls are available.
OnOpenPage Trigger | When the page is initialized and the controls are available.
OnClosePage Trigger | When the page about to close and after OnQueryClosePage Trigger trigger.
OnFindRecord Trigger | When the page is opened and a record is retrieved from a table.
OnNextRecord Trigger | When the page changes from displaying one record to another record in a table. For example, on a Customer card page, this happens when a user selects Next (CTRL+PAGE DOWN) or Previous (CTRL+PAGE UP).
OnAfterGetRecord Trigger | When a record has been retrieved but not yet displayed.
OnNewRecord Trigger | When a new record has been initialized but not yet displayed.
OnInsertRecord Trigger | When a new record is about to be inserted in the table.
OnModifyRecord Trigger | When a record is about to be modified in the table.
OnDeleteRecord Trigger | When a record is about to be deleted from the table.
OnQueryClosePage Trigger | When the page is about to close, but before the OnClosePage Trigger.

Field Triggers

The following table describes the triggers that are available on field controls.

Control trigger | Executed
OnValidate (Controls) Trigger | When the user changes the value in a field and then clicks away from the field so that the field loses focus.
OnLookup (Controls) Trigger | When the user requests a lookup by clicking a field's lookup button or pressing F4.
OnDrillDown Trigger | When the user requests a drill-down by clicking the field's drill-down button or pressing SHIFT+F8.
OnAssistEdit Trigger | When the user requests assist-edit by clicking an AssistEdit button or by pressing SHIFT+F4.
OnControlAddin Trigger | When a control add-in is initiated on a page.

Action Triggers

The following table lists triggers that apply to actions on a page.

Triggers | Executed
OnAction Trigger | When an action is initiated on a page.

See Also

Concepts

Triggers
Form Triggers
Form Control Triggers


OnAction Trigger

OnAction Trigger

Executes when a user selects an action on a page.

OnAction()

Expand image Applies To

  • Page actions

Expand image Remarks

This is called after the action properties, such as the RunObject Property, are invoked.

You typically use the RunObject Property to run objects such as pages, reports, and codeunits from an action. You can use the OnAction trigger when you require more processing than the RunObject Property can support, such as filtering data before a page is displayed or writing to the database.

To see an example of the OnAction trigger in use, see Walkthrough: Debugging an Action on a Page.

Note Note

The OnAction trigger is not used on Role Center pages. If you add C/AL code to the trigger, the Role Center page will compile, but the C/AL code will be ignored at runtime.

Expand image See Also

Tasks

Walkthrough: Debugging an Action on a Page

Concepts

Page and Action Triggers


OnClosePage Trigger

OnClosePage Trigger

Executes as a page closes after the OnQueryCloseForm Trigger trigger is executed.

OnClosePage()

Expand image Remarks

This trigger is initiated by a user action, such as when the user clicks the Close button, or by the CurrPage.CLOSE function being called.

You can write to the database from within this trigger.


OnControlAddin Trigger

OnControlAddin Trigger
See Also Example
CollapseAll image

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Executes when a control add-in on the RoleTailored client page sends event information to the server-side business logic. You add C/AL code to process the data that is sent with the event.

OnControlAddin(Index ; Data)

Parameters

Index

Type: Integer

An integer identifier that a control add-in sends with the event.

Data

Type: Text or BigText

A text string that a control add-in sends with an event.

Note Note

The data type is determined by the binding target that is specified in the SourceExpr Property of the page field control. If the binding target is of type BigText, then the Data parameter is BigText. Otherwise, the Data parameter is Text

Expand image Applies To

  • Page field controls

Expand image Remarks

An example of an event is when a user clicks a button in the control add-in user interface or when a user changes a value in a field. A control add-in can use events like these to invoke the OnControlAddin trigger and pass information as an integer in the Index parameter and as a text string in the Data parameter. To process the information, you add the C/AL code to the OnControlAddin trigger. For more information, see Calling C/AL Triggers from a RoleTailored Client Control Add-in.

Expand image Example

The following is an example of C/AL code on a OnControlAddin trigger that takes a text string that is received from a control add-in event and then displays the text string in a message window. Because the information is a text string, the Data parameter is used. To see how to develop and use a sample control add-in that implements this event, see Walkthrough: Creating and Using a RoleTailored Client Control Add-in.
CopyCode image Copy Code
Message(Data);

Expand image See Also

Tasks

How to: Set up a RoleTailored Client Control Add-in on a Page

Concepts

RoleTailored Client Control Add-in Overview
Developing RoleTailored Client Control Add-ins
Calling C/AL Triggers from a RoleTailored Client Control Add-in


OnOpenPage Trigger

OnOpenPage Trigger

Executes after a page is initialized and run.

OnOpenPage()

Expand image Applies To

  • Pages

Expand image Remarks

This trigger executes after the OnInit Trigger.

You use the OnOpenPage trigger to change dynamic properties, including those which can only be changed when the page is opened, such as the Visible Property. You can also write to the database from the trigger.

If an error occurs in the trigger execution, then the page closes.

Note Note

If you use the LOCKTABLE Function (Record) in the OnOpenPage trigger, then the table lock will be released when the trigger completes execution and not when the user closes the page.


OnQueryClosePage Trigger

OnQueryClosePage Trigger

Executes as a page closes and before the OnClosePage Trigger executes.

[Ok]:= OnQueryClosePage

Expand image Return Value

Ok

Type: Boolean

true to close the page; otherwise false. This value is checked after each function call.

Expand image Applies To

  • Pages

Expand image Remarks

If the page that is closing and all its child pages return true in the OnQueryClosePage trigger, then the OnClosePage Trigger is called for all child pages and then for the parent page.

If an error occurs in the OnQueryClosePage trigger or it returns false, then the page is not closed.

You can use this trigger to write to the database.


OnValidate (Page) Trigger

OnValidate (Page) Trigger

Executes when a field loses focus after its value has been changed.

OnValidate()

Expand image Applies To

  • Pages

Expand image Remarks

Use this trigger to validate user entries in a page field. If validation fails, then the field is marked with an error and its value is not saved.

The OnValidate trigger is also a field trigger at the table level. For more information, see OnValidate (Fields) Trigger. If both the table field and page field triggers are defined, then the OnValidate trigger on the table field is executed before the OnValidate trigger on the page field.

Note Note

You can use this trigger to write to the database. You cannot call the UPDATE function from this trigger.


Codeunit Triggers

Codeunit Triggers

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

The following triggers apply to codeunits.

Codeunit trigger name | Executed
OnBeforeTestRun Trigger | Before a test function of a test codeunit is run.
OnAfterTestRun Trigger | After a test function of a test codeunit is run.

See Also

Tasks

How to: Create Test Codeunits and Test Functions

Concepts

Testing the Application


OnAfterTestRun Trigger

OnAfterTestRun Trigger
See Also Example
CollapseAll image

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Executes after a test function of a test codeunit has been run.

OnAfterTestRun(CodeunitID : Integer;CodeunitName : Text[30];FunctionName : Text[30];Success : Boolean)

Parameters

CodeunitID

Type: Integer

The ID of the codeunit that has run.

CodeunitName

Type: Text

The name of the test codeunit that has run.

FunctionName

Type: Text

The name of the test function that has run.

Note Note

This parameter is empty when the OnAfterTestRun trigger is called for the entire test codeunit.

Success

Type: Boolean

true indicates that the test function run succeeded. false indicates that the test function run failed.

Expand image Applies To

Test runner codeunits. Test runner codeunits have the SubType Property (Codeunit) set to TestRunner.

Note Note

This trigger is optional and not available on a test runner codeunit by default. To implement this trigger, you must manually add it as a function.

Expand image Remarks

A test runner codeunit manages the execution of test codeunits that are run from its OnRun function. When a test codeunit runs, it executes each test function one at a time in the codeunit. When implemented, the OnAfterTestRun trigger is called after each test function has run and after the entire test codeunit has run.

The OnAfterTestRun trigger suppresses the automatic display of the results message after the test codeunit runs.

Note Note

To return the error message for a failed test function run, use the GETLASTERRORTEXT Function.

You can use the OnAfterTestRun trigger to perform postprocessing, such as logging, or to automate tests by integrating the test runner codeunit with a test management framework.

The OnAfterTestRun trigger is run in its own database transaction.

For more information, see Testing the Application and How to: Create a Test Runner Codeunit.

Expand image Example

The following OnAfterTestRun trigger code logs test results to a test reporting system. This example requires that you create a record variable named log.
CopyCode image Copy Code
log.INIT;
log.UnitId := CodeunitId;
log.Unit := CodeunitName;
log.Func := FunctionName;
log.Before := Before;
log.After := CURRENTDATETIME;
If Success THEN
  log.Status := log.Status::Success
ELSE BEGIN
  log.Status := log.Status::Failure;
  IF FunctionName <> '' THEN
    log.Message := GETLASTERRORTEXT;
END
log.INSERT(true);

The GETLASTERRORTEXT function returns the text that was contained in the last error message.

Expand image See Also

Tasks

How to: Create a Test Runner Codeunit
How to: Create Test Codeunits and Test Functions
How to: Create Handler Functions
Walkthrough: Testing Vendor Discount

Reference

OnBeforeTestRun Trigger

Concepts

Testing the Application


OnBeforeTestRun Trigger

OnBeforeTestRun Trigger
See Also Example
CollapseAll image

Note Note

The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

Executes before a test function of a test codeunit is run.

OnBeforeTestRun(CodeunitID : Integer;CodeunitName : Text[30];FunctionName : Text[30]) Ok : Boolean

Parameters

CodeunitID

Type: Integer

The ID of the codeunit to be run.

CodeunitName

Type: Text

The name of the test codeunit to be run.

FunctionName

Type: Text

The name of the test function to be run.

Note Note

This parameter is empty when the OnBeforeTestRun trigger is called for the entire test codeunit.

Expand image Return Value

Ok

Type: Boolean

true to run the test function; otherwise, false. This value is checked after each function call.

Expand image Applies To

Test runner codeunits. Test runner codeunits have the SubType Property (Codeunit) set to TestRunner.

Note Note

This trigger is optional and not available on a test runner codeunit by default. To implement this trigger, you must manually add it as a function.

Expand image Remarks

A test runner codeunit manages the execution of test codeunits that are run from its OnRun function. When a test codeunit runs, it executes each test function in the codeunit, one at a time. The OnBeforeTestRun trigger is called before the test codeunit, the OnRun function, and each test function.

The OnBeforeTestRun trigger is run in its own database transaction.

You can use the OnBeforeTestRun triggers to perform preprocessing, such as general initialization and logging, or to automate tests by integrating the test runner codeunit with a test management framework.

For more information, see Testing the Application and How to: Create a Test Runner Codeunit.

Expand image Example

The following OnBeforeTestRun trigger code initializes a logging variable and returns true to indicate that the test function should execute. This example requires that you create the following global variable.

Name | DataType
Before | DateTime
CopyCode image Copy Code
Before := CURRENTDATETIME;
EXIT(true);

Expand image See Also

Tasks

How to: Create a Test Runner Codeunit
How to: Create Test Codeunits and Test Functions
How to: Create Handler Functions
Walkthrough: Testing Vendor Discount

Reference

OnAfterTestRun Trigger

Concepts

Testing the Application


Information

Information

This section contains the following topics:

  • Composing URLs

  • Event Triggers

  • FlowFields

  • FlowFilters

  • Import Worksheet

  • MenuSuite Object

  • Microsoft Dynamics NAV Application Server

  • Options for Merging Objects

  • RGB Color Model

  • SQL Server Data Types

  • SumIndexFields

  • xRec and FIELDNO


Composing URLs

Composing URLs
Example
CollapseAll image

You can use uniform resource locators (URL) to open elements in the Classic client. URLs have the following syntax:

navision://client/run?name1=value1&name2=value2...&name n &value n

The syntax of each argument is <name>=<value>. Arguments are separated by the "&" character. A name is case insensitive and may contain any alphanumeric character. A value is a case sensitive string that can contain any character. You can provide any number of arguments in any order. Unknown arguments are ignored.

Valid name characters: [A..z] and [0..9]

Valid value characters: all

If a value contains the "&" character, then you must use another "&" character as an escape character to indicate that & is part of the value. For example, if the company name is City Power & Light, then the following URL opens this company and runs the Customer List form:

CopyCode image Copy Code
navision://client/run?company=City Power && Light&target=form Customer List

Expand image Arguments

The following table shows URL arguments.

Argument name Argument value Applies to Description

servername

Server name

Forms and reports

Indicates which database server to which the Classic client or Microsoft Dynamics NAV Server connects.

Note Note

Use either "servername" or "database" as the argument.

database

File name

Forms and reports

Indicates which database file to access.

Note Note

Use either "server" or "database" as the argument.

company

Company name

Forms and reports

Indicates which company to open.

target

Object

Forms and reports

Indicates which object to run. Valid argument values are the following:

  • form xxx

  • formxxx

  • Form xxx

  • Formxxx

  • report xxx

  • reportxxx

  • Report xxx

  • Reportxxx

Where xxx is either the object number or object name.

view

View description

Forms and reports

Indicates which filter to set. The format is the same as for the SourceTableView Property on a form.

position

Record description

Forms

Indicates which record to select. The format is the same as for the SourceTablePlacement Property on a form.

servertype

MSSQL or NAVISION

Forms and reports

Indicates which server to connect to.

requestform

Yes or no

Reports

Indicates whether a report should display its request form. The default value is no.

forcenewinstance

Yes or no

Forms and reports

Indicates whether a new instance of the Classic client should be started regardless of whether a suitable instance is running. The default value is no.

If you choose a running client as the target for the URL, the values are ignored for the server, the database, and the company because they have been used to select the particular running client.

If you choose a new client as the target for the URL, the default values are stored for the server, the database, and the company in the .zup file.

You must only use URLs without a specified server, database, or company when you link to program functionality, such as the customer card, and not when you link to data in the program, such as a view of a customer on a customer card.

Expand image Example

The following strings are examples of internal URLs. C/AL code cannot handle external URLs because of undefined escape characters. The only defined escape character is the "&&" character.
CopyCode image Copy Code
navision://client/run?servertype=NAVISION&database=c:\database.fdb&company=dot.com&target=Form991&forcenewinstance=yes
// The following example contains a URL with field names:
navision://client/run?servername=navi_srv1&company=CRONUS International Ltd.&target=Form Account Schedule&view=SORTING(Schedule Name,Line No.)&position=Schedule Name=CONST(),Line No.=CONST(0)&servertype=MSSQL
// The following example contains a URL with field numbers:
navision://client/run?servername=navi_srv1&company=CRONUS International Ltd.&target=Form 104&view=SORTING(Field1,Field2)&position=Field1=0(),Field2=0(0)&servertype=MSSQL


Event Triggers

Event Triggers

The following information is useful when you have enabled C/SIDE to receive events from a component that it controls, for example, an automation server.

There are certain limitations on the triggers that are automatically generated for the events, which the component provides. Furthermore, incoming data is subject to certain restrictions.

Expand image Limitations

The following are the limitations exist for event triggers:

  • C/SIDE only supports the default outgoing, that is, source interfaces, which are defined by the automation variable. If more than one outgoing interface is defined by the automation server for a coclass, only event triggers for the default outgoing interface are generated in the C/AL code.

  • There can be a maximum of 39 parameters in function calls.

  • There can be a maximum of 1024 characters in prototype text strings for functions.

  • The connectable object strategy in COM is used to connect Microsoft Dynamics NAV and the automation server. The Sink object defined in this strategy and implemented in Microsoft Dynamics NAV only supports the IDispatch interface (and IUnknown). It is therefore expected that the automation server calls on IDispatch when executing events.

  • Parameter names will be truncated to a maximum of 30 characters.

  • There are no return values on event triggers.

  • The variable name along with "::" and the event trigger name will be truncated to a maximum of 30 characters.

Expand image Restrictions on Incoming Data

All received data is copied to an internal data type, which can handle any data type that COM allows. No data is lost in this conversion and there is no check for valid AL data types.

The data will remain in this internal data type until it is used inside the trigger. When data is used, it is converted to the appropriate C/AL data type. Note, however, that if the data type is Variant, no conversion occurs. No data is lost in the conversion and all the required checks are made. If the conversion is not possible because there is an invalid data type, or because data is outside the range, the event trigger causes an error message to displays and terminates execution. If data is never used in the event trigger, no checks for valid data, data type, and data range are performed.

If parameter is a VAR parameter (that is, called ByRef) and data is used inside the event trigger, there will be an implicit conversion just before the event trigger returns. A check is made of whether conversion is possible. If this is not the case, an error message is displays and the event trigger terminates.


FlowFields

FlowFields

FlowFields display the result of the calculation described in the CalcFormula Property. For example, the Account Balance field in the General Ledger Account table shows the balance of the account and is calculated as the sum of the NetAmount fields for all General Journal entries in the account.

You can use FlowFields to do the following:

  • Calculate the total of a field over a set of records and display the results.

  • Calculate averages.

  • Determine the existence of records in a table.

  • Determine the number of values in a table.

  • Determine the minimum value.

  • Determine the maximum value.

  • Look up a value in another column in another table.

FlowFields are not physical fields stored in the database. Instead, they are a description of a calculation and a place for the result to be displayed. To update a FlowField, you must use the CALCFIELDS Function (Record).


FlowFilters

FlowFilters

You use FlowFilter fields to set ranges on the calculations that are shown in FlowFields. For example, if a FlowField contains the total of customer entries, then you can use a FlowFilter to see the total for a single month or range of months. In this example, the FlowFilter field is a date field. You can set up FlowFilter fields to show information that is based on other filters such as business units, departments, or projects.

FlowFilter fields are not saved in the database. Instead, they are stored for each window on an individual computer so users have their own filters.

Expand image Differences Between the Classic Client and the RoleTailored Client

In the Classic client, you can have a FlowFilter field as the SourceExpr value for a control on a form. When you run the form, you can select a value for this control and filter the data that is displayed in the form.

In the RoleTailored client, you cannot have a FlowFilter field as the SourceExpr value for a control on a page. If you do, then the control on the page is not editable, and you cannot select a value and filter the data that is displayed in the page. When you transform a form with a FlowFilter control to a page, we recommend that you specify that the control is deleted from the transformed page in the transformation input. For more information, see How to: Exclude Specific Controls from Transformation.

To enable filtering data on a page, you can add a Filter pane to the page and use limit totals. For more information, see the Page Controls and Parts section of Touring the RoleTailored Client Pages.


Import Worksheet

Import Worksheet

The Import Worksheet is a form that is used during binary import of objects. If the import file contains only objects that are either new or have been updated, they will be imported. If, however, one or more objects with the same ID Property already exist, a decision must be made about what to do. The Import Worksheet displays information about both existing and new objects, and lets you decide how to handle conflicts.

The functions of the Import Worksheet (version check and so on) are only relevant for binary objects (files with a .fob extension). Objects in text format are always imported, regardless if they overwrite existing objects.

Expand image How to Import Objects

To import objects, do the following:

  1. Click Tools and then click Object Designer.

  2. Click File and then click Import.

  3. In the Import Objects window, select the file that contains the binary objects from the dialog. These files have a .fob extension.

  4. After you choose a file, it will be examined. Depending upon the contents of the file, one of the following occurs:

    • If the file contains new or updated objects only, you will be asked if you want to import it now. If you click Yes, the objects will be imported. If you click Cancel, the import will be aborted. If you click No, the Import Worksheet (described below) is displayed.

    • If there are conflicts, you will be informed of them and you can choose either to cancel the import or go to the Import Worksheet by clicking OK.

    • There are two kinds of conflicts. The first may occur if the version list numbers of the new and the existing objects are not the same. The second may occur if the default actions that were created by storing the Import Worksheet settings in the file with the objects are not valid because the versions of the objects in the database are different from when the file was created.

Expand image Default Actions in the Import File

The value of the Action option for each object in the Import Worksheet can be saved in the file with the objects. This means that how conflicts should be resolved can be decided when the file with the objects is created. When importing, you can choose to revise these settings by clicking No in the dialog box that appears after the file has been examined, or you can choose to import the objects.

If the assumptions that were made when the settings were saved are no longer valid, you must revise the settings. This is the case if the objects in your database are not the same as the objects that were used to create the file.

Expand image The Import Worksheet

Each line in the Import Worksheet displays information about one object and allows you to decide how to handle the object by setting the Action option. The following table shows the information that is displayed about each object, and, in addition, the Name, Modified, Version List, Size, Date, and Time fields are displayed on the form for the object that has the focus.

Type

The type (such as form or report) of this object.

No.

The ID of the object.

Name

The name of the (new) object.

New Object

This option is selected if this is a new object that was not in the database before.

New Object Changed

This option is selected if the new object has been marked as changed.

Existing Object Changed

This option is selected if the existing object has been changed, for example, the modified flag set or version list changed.

Note Note

If a warning icon is displayed in this column, it means that there is a conflict that must be resolved before this object can be imported.

Action

This option is the only field with contents that can be changed. This setting determines how a conflict will be resolved. The options are the following:

  • Create The new object will be added to the database. This option is only valid if no such object already exists.

  • Replace The existing object will be replaced by the new object.

  • Delete The existing object will be deleted and no new object created. This option is only valid if the new object has size 0. The intended use is to remove obsolete objects from the database.

  • Skip This object will not be imported.

  • Merge: Existing<-New Only valid for tables. All fields in the existing table will remain and any additional fields from the new object will be added.

  • Merge: New<-Existing Only valid for tables. All fields in the new table will be imported and any additional fields in the existing table will be added to the new table.

Existing Object Modified

This option is selected if the existing object has the Modified field set to Yes.

Existing Object Version List

The version list of the existing object.

New Object Modified

This option is selected if the new object has the Modified field set to Yes.

New Object Version List

The version list of the new object.

Expand image Using the Import Worksheet

For each object, you can choose an action, given the constraints outlined in the preceding table. You can apply these actions by clicking the appropriate buttons.

Action | Definition
OK | Perform the import according to the current settings in the worksheet.
Cancel | Cancel the import.
Replace All | Set Action for all objects to Replace.
Save As | Save the current settings in the worksheet in the import file, together with the objects.
Help | Display the Help topic.


MenuSuite Object

MenuSuite Object

The MenuSuite object contains the menus that are displayed in the Navigation Pane and in the Navigation Pane Designer. Each menu contains content for a specific departmental area, for example, Finance or Manufacturing.

A menu suite has the following characteristics:

  • It consists of a set of menus.

  • A menu contains a collection of menu nodes, which are displayed in a tree structure.

  • A menu node can be either a menu group or a menu item.

  • Each menu node has a GUID.

  • A menu group contains a collection of menu nodes.

  • A menu item is the lowest level in the tree. When you click a menu item, its associated form, report, batch job, dataport, or codeunit is run.

Creating and Designing MenuSuite Objects

You access a MenuSuite object from the Object Designer by clicking MenuSuite. You then have the following options:

  • Click New to open a dialog box to specify for which design level you want to create an object. If you have already created MenuSuite objects for all the levels that you have permission to, a message is displayed. After you select the design level, the Navigation Pane Designer opens, and you have the design permissions associated with that level.

  • Select a MenuSuite object and then click Design to open the Navigation Pane Designer with the chosen menu suite content displayed.

  • Select the File and then click Import or Export to import and export files.

  • Click Tools, click Translate, and then click Import or Export for Translate import and export.

  • Click Tools and then click Compile to compile a MenuSuite object. The object references are compiled. If the MenuSuite object contains a reference to a non-existing form, report, batch job, dataport, or codeunit, a compilation error occurs.

The Run function in the Object Designer is disabled for MenuSuites.

Design Permissions

You can create new forms or reports and insert these into menus as menu items. You can also make modifications to existing application objects. You have the same design permissions as an administrator. As a developer working as a Microsoft Certified Partner, you have permission to create a MenuSuite object at the Partner level. You also have permission to create a MenuSuite object at the Company level, which can be useful for testing before you supply a company with a MenuSuite object.

See Also

Reference

Customizing a MenuSuite
Create Item in Navigation Pane Designer
Design Level
Item Properties
Exporting a MenuSuite Object
Upgrading Menu Suite Content


Customizing a MenuSuite

Customizing a MenuSuite

You customize a menu suite in the Navigation Pane Designer. To access the various design options, right-click menu buttons, menu groups, menu items, or anywhere in the content pane area. In addition to having access to the same design options as an administrator, you can do the following:

  • Create new menu items by specifying object type, object ID, caption, and multilanguage caption.

  • Set Object Type, Object ID, Caption, and CaptionML properties for a menu item.

Expand image MenuSuite Object Levels

A generic MenuSuite object is provided at the MBS level. This object is changed in various ways before end-users see its content. These changes are applied at different levels, which have been categorized as Country/Region, Add-on, Partner, and Company. For example, the MenuSuite object is changed when the application requires localization changes. This takes place at the Country/Region level. As a developer working at a Microsoft Certified Partner, you customize a MenuSuite object at the Partner level. You can also configure a MenuSuite object at the Company level, which is the level that administrators work on. When designing a MenuSuite object, the header area of the Navigation Pane Designer displays text to indicate the level that you are working on.

Changes that are made to a MenuSuite object are stored as the differences between the previous MenuSuite object level and the current one. For example, when a company administrator configures a MenuSuite object at the Company level, the modifications are stored as the differences between the Company level and the Partner level, which was the previous level. If you export a MenuSuite object in text format and then open the text file, you will see information about the changes that you have made in comparison with the previous level. For more information about exporting a MenuSuite object, see Exporting a MenuSuite Object.

There can only be one MenuSuite object for each level, with the exception of the Add-on MenuSuite object, for which there can be a maximum of 10 instances.

Expand image See Also

Concepts

MenuSuite Object


Create Item in Navigation Pane Designer

Create Item in Navigation Pane Designer

To create an item in the Navigation Pane Designer, right-click an item in the content pane area, and then click Create Item. In the Create Item window, specify the Object Type, Object ID, Caption, and CaptionML (multilanguage caption) of the menu item that you want to add to a menu. For example, if you have created a new report and want to add it as a menu item to a particular menu, then select Report in the Object Type field drop-down list and use the lookup in the Object ID field to select the report from the Report List window. Click the Caption field for the name of the report to be automatically entered. You can change the Caption field if necessary. By default, the CaptionML field shows the code for the language that you use on your computer and the name of the menu item. If you have designed a menu item that will be used in different languages by different users, you must give the menu item a name in each language. Click the AssistButton to open the Multilanguage Editor in which you can enter a menu item name for each language code.

Expand image See Also

Reference

Item Properties


Item Properties

Item Properties

In the Create Item window, you can set properties for the menu item that you have selected. For example, you may want the menu item to point to a different application object. The following table describes the properties.

Property Description

Object Type

Select one of the following types:

  • Table

  • Form

  • Report

  • Batch job

  • Codeunit

  • Dataport

Note Note

The RoleTailored client does not support Form or Dataport object types.

Object ID

Use the lookup to select an object from a list. For example, if you select Report as the object type and then click the lookup in Object ID, the Report List is displayed.

Caption

By default, the Caption field contains the name that is assigned to the menu item. You can rename it here.

CaptionML

The CaptionML field contains the code for the language that you use on your computer and the name of the menu item, for example, ENU=General Journals. If the menu item will be used in different languages, you must give the menu item a name in each language. Click the AssistButton in the CaptionML field to open the Multilanguage Editor. In the Multilanguage Editor, you can enter a menu item name for each language code.


Design Level

Design Level

You can select the MenuSuite object level that you want to design. The form displays the levels that you have permission to use.

A generic MenuSuite object is provided at the MBS level. This object is changed in various ways before end users see its content. These changes are applied at different levels, which have been categorized as Country/Region, Add-on, Partner, and Company. For example, the MenuSuite object is changed when the application requires localization changes. This takes place at the Country/Region level. If you are a developer working as a Microsoft Certified Partner, you customize a MenuSuite object at the Partner level. You can also configure a MenuSuite object at the Company level, which is the level that administrators work on. When you are designing a MenuSuite object, the header area of the Navigation Pane Designer displays text to indicate the level that you are working on.

There can only be one MenuSuite object for each level, with the exception of the Add-on MenuSuite object, for which there can be a maximum of 10 instances.


Exporting a MenuSuite Object

Exporting a MenuSuite Object
Example
CollapseAll image

You can export a MenuSuite object in Microsoft Dynamics NAV object format (*.fob) or in text format. When you export a MenuSuite object in text format, the text file contains information about the changes that have been made to the object since the previous level. This topic shows an example of a text file which contains the changes that have been made to a MenuSuite object at the Company level. For more information about MenuSuite object levels, see Customizing a MenuSuite.

Expand image Example

When an administrator makes configuration changes to a MenuSuite, these changes are saved at the Company level. When this Company-level MenuSuite object is exported in text format, the text file contains information about the changes that have been made to the object since the previous level, which in this case would be the Partner level. In the following example, an administrator has made the following changes to his company's menu suite:

  • In the Finance menu, deleted a menu group called Setup, which contained one menu item called Accounting Periods.

  • Added a new menu item, G/L Account Card, to the General Ledger menu group in the Finance menu.

  • Moved the G/L Account Card menu item so that it is placed between the Chart of Accounts and Bank Accounts menu items in the General Ledger menu group.

The text file contains the following information.
CopyCode image Copy Code
OBJECT MenuSuite 70 Company
{
  OBJECT-PROPERTIES
  {
    Date=19-04-04;
    Time=16:04:10;
    Modified=Yes;
    Version List=;
  }
  PROPERTIES
  {
  }
  MENUNODES
  {
    { MenuItem       ;[{FA8395A4-7A0B-4524-B0FD-20436D9711A4}] ;Name=G/L Account Card;
                                                                CaptionML=ENU=G/L Account Card;
                                                                MemberOfMenu=[{F8D2429D-034B-4C58-9B5E-81BE962DB1BC}];
                                                                RunObjectType=Form;
                                                                RunObjectID=17;
                                                                ParentNodeID=[{B12180CF-0EFB-43AD-9118-7765E953AAFD}];
                                                                Visible=Yes;
                                                                NextNodeID=[{7A5B6DDE-B44B-41A0-95DA-69B7109F0E32}] }
    {                ;[{1BB06483-AFFD-4750-BF62-3ABA035E11B7}] ;Deleted=Yes }
    {                ;[{DF601C8A-07F7-4841-8929-9F2065BCB302}] ;Deleted=Yes }
    {                ;[{8AC7917D-2C91-457D-80D6-A24B42F71AE7}] ;NextNodeID=[{FA8395A4-7A0B-4524-B0FD-20436D9711A4}] }
  }
}

Each menu node has a GUID and various properties.


Upgrading Menu Suite Content

Upgrading Menu Suite Content

Menus in a MenuSuite that are inherited from the previous MenuSuite object level have the symbol >> on the menu button to the left of the menu name. These menus will be upgraded when you upgrade the corresponding MenuSuite object. Any changes that you have made to these menus will be merged into the new MenuSuite when you upgrade. For example, a menu item that you have added to a menu group, but where the menu group’s contents now have changed after an upgrade, will be placed as the last menu item in the menu group.

However, there will be cases where a straightforward merge cannot be carried out. For example, if you have added a menu item to a menu group that is no longer a part of the menu after an upgrade, then no merge can be made. Instead, the menu item will be placed in a Lost Items group at the bottom of the menu tree. In another example, if you had added one or more menu items to a menu that is no longer present in the menu suite after an upgrade, the menu items will be placed in a Lost Items menu.

After an upgrade, you can take action on the menu items in a Lost Items group or menu, either by inserting them in the current menu (in the case of the Lost Items group), or by inserting them in another menu, or by deleting them. A Lost Items group or menu is not visible in the Navigation Pane at runtime.

New menus that you have created are not affected by an upgrade. If there are new menu items available after the upgrade that you want to insert in these menus, you must add them manually.


Microsoft Dynamics NAV Application Server

Microsoft Dynamics NAV Application Server
Example
CollapseAll image

The Microsoft Dynamics NAV Application Server, sometimes referenced as the Classic server, is a Classic Architecture component in Microsoft Dynamics NAV 2009. There is no graphical user interface (GUI) on the Microsoft Dynamics NAV Application Server, therefore, there are some limitations on the C/AL code that can run on the application server. For more information, see the GUIALLOWED Function.

The following functions are available when running Microsoft Dynamics NAV Application Server:

  • All system functions except the GUI-related functions such as Dialog Data Type functions

  • OCX Data Type functions and Automation Data Type functions

  • Codeunit Data Type functions

  • File Data Type functions

The following functions are not available in Microsoft Dynamics NAV Application Server:

  • Form Data Type functions

  • Dataport Data Type functions

Expand image Error Logging

When you run C/AL code with triggers containing functionality that invokes GUI, an error occurs. A corresponding error message is posted in the NT event log. For more information about message logging, see the manual "Installation & System Management: Microsoft Dynamics NAV Application Server".

Calls to the following functions will create errors:

  • FORM, DIALOG, and CONFIRM: An error is displayed when the Application server runs from the Microsoft DOS command line. When Microsoft Dynamics NAV Application Server runs as a service, an error message is logged.

  • MESSAGE and ERROR: An error message is logged.

Note Important

REPORT and DATAPORT functions are not available. OCX and AUTOMATION functions are available. However, if they invoke GUI functions, they may cause Microsoft Dynamics NAV Application Server to stop running. The only way to restart the Application server is to reboot.

Expand image Starting the Microsoft Dynamics NAV Application Server

Before you can successfully start a Microsoft Dynamics NAV Application Server, you must create a startup trigger on codeunit 1 with ID number 99. The trigger must have a parameter of type Text, with a maximum length of 1024 characters. This parameter is passed to the codeunit trigger, which is always executed when Microsoft Dynamics NAV Application Server starts. This trigger is not defined in the standard application. The interpretation of the text string is the responsibility of the C/AL programmer. If you do not supply the parameter, the Microsoft Dynamics NAV Application Server startup procedure fails.

Expand image Communication Between Microsoft Dynamics NAV Client and Microsoft Dynamics NAV Application Server

To establish communication between a Microsoft Dynamics NAV Classic client and Microsoft Dynamics NAV Application Server, you need to start a timer. You can make the Application server start a timer that triggers an event at a certain interval. When Microsoft Dynamics NAV Application Server receives the event, it can check the database for unprocessed tasks, such as an order.

A user that runs a Microsoft Dynamics NAV Classic client can put, for example, a 'send order' task in the task table in the database. Microsoft Dynamics NAV Application Server can then check the database for this task.

Expand image Example

This is an example of what the startup trigger can look like. First, the trigger instantiates a communication component. Then, if the parameter passed equals 'Test,' the application server is instructed to also look in the task table. The 'Test' parameter starts a timer.
CopyCode image Copy Code
InitComCom.RUN;
CASE StartupParm OF
 'Test': InitializeTaskTable.RUN;
END;


Options for Merging Objects

Options for Merging Objects

The following sequence of events shows when objects are merged:

  1. The old object is decompiled.

  2. The new object is decompiled.

  3. The objects are merged.

  4. The resulting object is compiled.

If any of these steps fail, the merge will be discontinued.

There are two options for merging:

  • Existing <- New

  • New <- Existing

Expand image Existing <- New

Using Existing <- New, the following items from the existing object are always used:

  • Table properties

  • Local C/AL functions on the table, including local variables

  • Global variables

The following items are merged into the existing object from the new object:

  • New fields

  • Field properties that are different in the objects

  • Trigger code on field level, including local variables

Fields are merged based on the field number. The following scenarios are possible:

  • The field exists in the old object, but not in the new. The field will be left as it was.

  • The field exists in the new object, but not in the old. The field will be added.

  • The field exists in both objects. If the properties are different in the new object, these new properties will be used.

This can lead to problems that have to be resolved manually. Consider, for example, a new object that differs from an old object by introducing code in a field trigger and this code uses a global variable that is not in the old object. The merge will fail because the global variables are taken from the old object, and the merged object needs the global variable in order to compile.

A workaround would be to declare the global variable in the old object before merging the objects.

Expand image New <- Existing

Using the New <- Existing option reverses the scenario.

The following items from the new object are always used:

  • Table properties

  • Local C/AL functions on the table, including local variables

  • Global variables

The following items are merged into the new object from the existing object:

  • New fields

  • Field properties that are different in the objects

  • Trigger code on field level, including local variables


RGB Color Model

RGB Color Model

The RGB color model is used for specifying colors. This model specifies the intensity of red, green, and blue on a scale of 0 to 255, with 0 (zero) indicating the minimum intensity. The settings of the three colors are converted to a single integer value by using this formula:

RGB value= Red + (Green*256) + (Blue*256*256)

The following table shows examples.

Red | Green | Blue | RGB value | Color
255 | 0 | 0 | 255 | Red
0 | 255 | 0 | 65280 | Green
0 | 0 | 255 | 16711680 | Blue
0 | 255 | 255 | 16776960 | Cyan
255 | 0 | 255 | 16711935 | Magenta
255 | 255 | 0 | 65535 | Yellow
255 | 255 | 255 | 16777215 | White
128 | 128 | 128 | 8421504 | Gray
0 | 0 | 0 | 0 | Black

Expand image Extracting Elements from an RGB Value

To extract the settings of the red, green, and blue elements from an RGB value, you can use the following method:

Convert the RGB value to a hexadecimal value. This will give you a hexadecimal number with up to six digits. From right to left, each pair of hexadecimal digits is the setting of red, green, and blue, respectively, and can be converted back to decimal. If the hexadecimal number contains less than six digits, fill out the number with zeroes on the left.

The following table shows examples.

RGB | Hexadecimal RGB | Red | Green | Blue
6579300 | 646464 | 100 | 100 | 100
16422450 | FA9632 | 50 | 150 | 250
32896 | 008080 | 128 | 128 | 0


SQL Server Data Types

SQL Server Data Types

Every available Microsoft Dynamics NAV data type is mapped to an appropriate SQL Server data type in the tables of the SQL Server Option for Microsoft Dynamics NAV. The following table shows which SQL Server data type is used for the corresponding Microsoft Dynamics NAV data type.

Microsoft Dynamics NAV Data Type | SQL Server Data Type
BigInteger | BIGINT
Binary(n) | VARBINARY(n)
BLOB | IMAGE
Boolean | TINYINT
Code(n) | VARCHAR(n), INTEGER, SQL_VARIANT
Date | DATETIME
DateFormula | VARCHAR(32)
Decimal | DECIMAL(38,20)
Duration | BIGINT
GUID | UNIQUEIDENTIFIER
Integer | INTEGER
Option | INTEGER
RecordID | VARBINARY(n)
TableFilter | VARBINARY(252)
Text(n) | VARCHAR(n)
Time | DATETIME

Each of the SQL Server data types is created as NOT NULL except the IMAGE type, which allows NULL.

There are other SQL Server data types than those listed in the previous table. You can use and modify these from within Microsoft Dynamics NAV when you have created or altered SQL Server tables or views outside Microsoft Dynamics NAV.

Some of the SQL Server data types listed previously are compatible with other Microsoft Dynamics NAV data types. The following table shows the extended compatibility of SQL Server data types with Microsoft Dynamics NAV data types.

SQL Server Data Type | Microsoft Dynamics NAV Data Type
BINARY(n) | Binary(n)
BIT | Integer, Option
CHAR(n) | Code(n), Text(n), DateFormula
INTEGER | Code
NCHAR(n) | Text(n)
NTEXT | BLOB
NUMERIC(p,s), MONEY, SMALLMONEY, REAL, FLOAT(n), DECIMAL | Decimal, Integer, Option, Boolean
NVARCHAR(n) | Text(n)
SMALLDATETIME | Date
SMALLINT | Integer, Option
TEXT | BLOB
TINYINT | Integer, Option, Boolean
UNIQUEIDENTIFIER | Binary(16), Text(36)


SumIndexFields

SumIndexFields let you quickly calculate the sums of numeric columns in tables, even in tables with thousands of records. SumIndexFields are the basis for the FlowFields in a C/SIDE application. This section describes how SumIndexField Technology (SIFT) works on Classic Database Server as well as how SIFT is implemented in Microsoft Dynamics NAV with Microsoft SQL Server. This information will help programmers develop efficient applications that use SumIndexField Technology.

SIFT

SIFT has been designed to improve performance when implementing such activities as calculating customer balances. In a traditional database system this involves performing a series of database calls and calculations before arriving at a result. The power and efficiency of SIFT on Classic Database Server makes calculating sums for numeric columns in tables very efficient, even in tables that contain thousands of records. This powerful feature is used throughout the Microsoft Dynamics NAV application in both database options.

SumIndexFields

A SumIndexField is associated with a key in the table. Each key can have up to 20 associated SumIndexFields. When you design your database, you can associate a decimal field with a key as a SumIndexField. This tells the Database Management System (DBMS) to create and maintain a structure that contains the accumulated sum of the values in a column. When a user selects a new key, any SumIndexFields associated with that key become accessible.

See Also

Concepts

SIFT and Classic Database Server
SIFT and Microsoft Dynamics NAV with Microsoft SQL Server


SIFT and Classic Database Server

SIFT and Classic Database Server

A SumIndexField is a fundamental feature which is the basis of FlowFields. A SumIndexField is associated with a key; each key can have a maximum of 20 SumIndexFields.

During database design, a field of the decimal type can be associated with a key as a SumIndexField. This tells the DBMS to create and maintain a structure which contains the accumulated sum of values in a column. When a new current key is selected, any SumIndexField associated with it becomes accessible.

Example

The following illustration shows a table where the Amount field (column) is defined as a SumIndexField in the Account No + Date key. This enables the DBMS to automatically maintain the accumulated sum of the column. Every time a change is made to a field in the column, the accumulated values are updated.

To the right of the table is shown an area in the database where the accumulated sums for the Amount column are kept. In the previous illustration, the third field in the column, with the accumulated sum, contains the value 600 because the first three Amount values are 100, 200, and 300, respectively—a total of 600. The fourth virtual field contains 1000, the total of the first four values in the Amount column, and so on. If the table contained a second SumIndexField, its values would be accumulated in the same way.

Advantages of SumIndexFields

With SumIndexFields sums (of columns) can be quickly calculated and the result displayed in FlowFields. If you want the sum of all the values in the Amount fields, in a conventional system, the DBMS is forced to access every record and add each value in the Amount field, This is a very time-consuming operation in a database with thousands of records. You would need to create a FlowField, define the calculation formula of this FlowField to sum the Amount field, so the DBMS only needs retrieve the value from the SumIndexField.

Operations with SumIndexFields are as fast when FlowFilter fields are applied. The second table in the previous illustration shows a group of records selected by a FlowFilter field in the Account No. field. Two records fulfil the conditions of the calculation filter.

Only two accesses are needed to sum the Amount for these records: one access to get the accumulated sum associated with the last record before the specified range, and one access to get the accumulated sum associated with the last record in the specified range.

The value 300 is subtracted from the value 1000 to produce the correct sum (700). No matter how many records there are in the selected range, the system will always need to perform only two accesses in order to compute the sum.

SIFT has been built into the index structure used on Classic Database Server and the more SumIndexFields that are added the larger the index becomes. However, the time used to maintain the accumulated sum for SumIndexFields is negligible due to a special index structure used in the DBMS.

See Also

Concepts

SIFT and Microsoft Dynamics NAV with Microsoft SQL Server


SIFT and Microsoft Dynamics NAV with Microsoft SQL Server

SIFT and Microsoft Dynamics NAV with Microsoft SQL Server

SIFT has also been implemented in the SQL Server Option for Microsoft Dynamics NAV. The way that SIFT is implemented on SQL Server has been changed with the introduction of the RoleTailored architecture. The following is a description of the way that SIFT is currently implemented in SQL Server.

Implementing SIFT in the SQL Server Option

A SumIndexField is always associated with a key and each key can have a maximum of 20 SumIndexFields associated with it. In this topic, a key that has at least one SumIndexField associated with it is a SIFT key. Any field of the Decimal data type can be associated with a key as a SumIndexField.

Microsoft Dynamics NAV uses "Indexed Views" to maintain SIFT totals. Indexed views are a standard SQL Server feature. An indexed view is similar to a SQL Server view except that the contents have been materialized (computed and stored) to speed up the retrieval of data. For more information about indexed views, see SQL Server Books Online.

Microsoft Dynamics NAV creates one indexed view for each SIFT key that is enabled. When you create a SIFT key for a table, you must set the MaintainSIFTIndex property for that key to Yes to enable the SIFT key and create the indexed view. After SQL Server has created the indexed view, it maintains the contents of the view when any changes are made to the base table. If you set the MaintainSIFTIndex property for that key to No, SQL Server drops the indexed view and stops maintaining the totals.

The indexed view that is used for a SIFT key is always created at the most finely-grained level. Therefore, if you create a SIFT key for AccountNo.,PostingDate, the database will store an aggregated value for each account for each date. This means that in the worst case scenario, 365 records must be summed to generate the total for each account for a year.

The following is an example of how Microsoft Dynamics NAV creates an indexed view for a SIFT key that consists of the "AccountNo., PostingDate" fields and generate the total for the Amount field.

CopyCode image Copy Code
CREATE VIEW GLEntry$VSIFT$1 AS SELECT SUM(Amount) as SUM$Amount,
AccountNo, PostingDate FROM GLEntry GROUP BY AccountNo,PostingDate*
CREATE UNIQUE CLUSTERED INDEX VSIFTIDX ON
GLEntry$VSIFT$1(AccountNo,PostingDate)*

The following C/AL code example retrieves a total.

CopyCode image Copy Code
GLEntry.SETCURRENTKEY("G/L Account No.","Posting Date");
GLEntry.SETRANGE(GLEntry."G/L Account No.",'1110');
GLEntry.SETRANGE(GLEntry."Posting
Date",DMY2DATE(1,1,2007),DMY2DATE(15,12,2007));
GLEntry.CALCSUMS(Amount);

The following code example shows how the same total is retrieved through an indexed view.

CopyCode image Copy Code
SELECT SUM(SUM$Amount) FROM GLEntry$VSIFT$1 WITH(NOEXPAND) WHERE
AccountNo=? AND PostingDate>=? AND PostingDate<=?

Note These SQL statements are only shown to illustrate this feature and their implementation could be subject to change at any time.

See Also

Concepts

Tuning and Tracing
SIFT and Performance


Tuning and Tracing

Tuning and Tracing

As a result of using indexed views, SIFT keys are exposed to SQL Server tracing and tuning tools. For example, the SQL Server profiler can display information about which indexed views are maintained for a specific table. This makes it easy for you to assess the cost of maintaining SIFT keys and allows you to make informed decisions about any adjustments that might be required.

SIFT Keys

When data is inserted, updated, or deleted in a table, the SIFT keys that have been defined and enabled for that table are maintained. Maintaining these SIFT indexes has performance overhead. The size of the performance overhead depends on the number of keys and SumIndexFields that have been defined for each table. You should therefore give careful consideration to the number of SIFT keys that you define and only maintain the SIFT keys that are important for your application.

There is no need to maintain a SIFT key for a total that is only used periodically and can be easily generated by a report. You can still program Microsoft Dynamics NAV to calculate the SIFT based totals even if the SIFT key is disabled. The calculation is performed directly on the base table.

You should consider combining indexes wherever possible.

Example

Maintaining two SIFT keys:

  1. Key: "WareHouseId, ItemId, Color" SumField: "OnStock"

  2. Key: "WareHouseId, ItemId, Size" SumField: "OnStock"

If there are only a few combinations of Size and Color (for example, less than 200), then one combined index/SIFT key should be sufficient.

  1. The Combined Key:

  2. "WareHouseId, ItemId, Color, Size" SumFIeld: "OnStock"

When you set the MaintainSIFTIndex property of a key to Yes, this will be the SIFT key and create the indexed view to support it. However, disabling the SIFT key by setting the MaintainSIFTIndex property to No can improve performance in certain circumstances. Setting this property to No means that the SIFT functionality must be implemented by calculating the totals online instead of using the precalculated sums that are maintained by SIFT.


SIFT and Performance

SIFT and Performance

This topic looks at the factors you must take into consideration when you deal with SIFT and performance.

Performance Factors to Consider

The factors that you must take into consideration when you deal with any performance problems that arise include:

  • Designing your SIFT indexes optimally.

  • Supporting too many SIFT indexes will affect performance.

  • Having unnecessary date fields in the SIFT indexes of the base table will affect performance because they create three times as many entries as an ordinary field.

  • Supporting too many fields in the SIFT indexes will also affect performance.

  • The fields in the SIFT index that are used most regularly in queries must be positioned to the left in the SIFT index. Usually, the field that contains the greatest number of unique values must be placed on the left, with the field that contains the second greatest number of unique values on the right and so on. Integer fields generally contain the greatest number of unique values and Option fields contain a relatively small number of values.

Consider the costs and the benefits of maintaining SIFT indexes.

Cost | Benefit
Updates to the SIFT indexes | Fast calculation of sums
Potential locking conflicts |

You can prevent the SIFT indexes from being updated by setting the MaintainSIFTIndex property of the index in the base table to No. This means that you no longer benefit from SIFT's ability to calculate sums quickly. However, the SIFT functionality is still available.

  • If the base table does not grow or only grows slowly, there is no need to set the MaintainSIFTIndex property of any indexes that contain SumIndexFields to Yes. If the base table does grow, you should set the MaintainSIFTIndex property of any indexes that contain SumIndexFields to Yes.

Note Important

It is important that you remember to perform tests every time you make any changes to the SIFT structures. You must ensure that the changes that you have made do not cause problems in any other areas of the application. You must also ensure that your changes do not have a negative affect on performance.

Note Note

If you set the MaintainSIFTIndex property to No, you should not set the MaintainSQLIndex to No.


xRec and FIELDNO

xRec and FIELDNO

When a user-defined function or a trigger is executed on a table object, xRec and FIELDNO are set differently, depending on how the function or trigger is executed. The following tables explain what happens in the different scenarios.

Expand image User-Defined Function

The following table explains what happens to xRec and FIELDNO when a user-defined function on a table object is called from either external or internal C/AL code. External C/AL code means that the calling code is in a different object. Internal C/AL code means that the calling code is in the same object (another function in the same object).

Execution initiated by | xRec value | FIELDNO value
External C/AL code | Empty | 0
Internal C/AL code | Unchanged | Unchanged

Expand image Triggers

The following table explains what happens to xRec and FIELDNO when a trigger is called from either external or internal C/AL code. External C/AL code means that the calling code is in a different object. Iinternal C/AL code means that the calling code is in the same object (another function in the same object).

Scenario | xRec value | FIELDNO Value
VALIDATE trigger called by external C/AL code that calls the VALIDATE function | Copy of Rec before assignment in VALIDATE trigger | Field number of field being validated
VALIDATE trigger called by internal C/AL code that calls the VALIDATE function | Unchanged | Unchanged
Any table or function called by C/AL that initiates a call to a trigger other than VALIDATE | Copy of Rec before trigger is executed | 0


C/SIDE Specifications and Limitations

C/SIDE Specifications and Limitations

This topic describes the specifications and limitations for the C/SIDE Database Management System (DBMS) and its application objects.

Expand image Specifications for the DBMS

Feature | Characteristic
Maximum number of physical disk files | 16
Database file size | 256 GB
Maximum number of objects in a database | Infinite
Maximum number of characters in application object names | 30
Maximum number of characters in a password | 10
Maximum number of concurrent users (the actual limit depends on your hardware and the workload) | 500
Maximum cache size | 1 GB

Expand image Specifications for Tables

Feature | Characteristic
Range for table object ID numbers | 1 – 999,999,999 1
Maximum number of characters in a table name | 30
Maximum table size | Infinite
Maximum number of records in a table | Infinite
Maximum record size | 4 KB
Maximum number of fields in a record | 500
Range for field numbers | 1 – 999,999,999
Maximum number of keys for a table | 40
Maximum number of distinct fields per key | 20 for a primary key. The number of fields in the primary key plus the number of fields in a secondary key which do not occur in the primary key must always be less than or equal to 20.
Maximum number of SumIndexFields per key | 20
Maximum number of characters in a text or code field | 250
Maximum size of a BLOB field | 2 GB
Maximum number of characters in a field name | 30

Expand image Specifications for Forms and Reports

Feature | Characteristic
Range for form or report object ID numbers | 1 – 999,999,999 1
Maximum form width | 100000 x 1/100 mm
Maximum form height | 100000 x 1/100 mm
Maximum number of nested forms | 1
Maximum number of controls on a form | 32767
Maximum number of characters in a label | 254
Maximum number of characters in a text box | 250
Maximum bitmap size in bitmap property | 32500 bytes
Maximum number of levels in drop-down menus | 10

Expand image Specifications for Codeunits

Feature | Characteristic
Range for table object ID numbers | 1 – 999,999,999 1
Maximum number of characters in variable names | 30
Maximum number of dimensions in array variables | 10
Maximum number of elements in an array variable | 1,000,000
Maximum physical size of a codeunit | 2 GB
Lower bound of index in an array | 1

1All application objects are identified by an ID number. There are restrictions, however, on the numbers you can use when you create your own application objects. Contact your Partner License Agreement for more information.

Expand image See Also

Concepts

Developing Objects


Special C/SIDE Tables

Special C/SIDE Tables

C/SIDE has three types of tables that serve special purposes in C/SIDE applications. These types of tables are:

  • Temporary

  • System

  • Virtual

Temporary tables are used as a repository for temporary information at run time. System and virtual tables are system generated tables that provide information about the current state of the system.

In This Section

C/SIDE Temporary Tables

C/SIDE System Tables

C/SIDE Virtual Tables

See Also

Concepts

Designing Tables


C/SIDE Temporary Tables

C/SIDE Temporary Tables

A temporary table is a temporary variable that holds a table. A temporary table is used as a buffer for table data in your C/AL programs. For more information about C/AL, see Introduction to C/AL.

You can use a temporary table just like you use a database table. The differences between a temporary table and a database table are:

  • A temporary table is not stored in the database, but is only held in memory until the table is closed.

  • The write transaction principle that applies to a database table does not apply to a temporary table. For more information, see Write Transactions and Recovery.

Advantage of a Temporary Table

The advantage of using a temporary table is that all the interaction with a temporary table takes place on the client. This reduces the load on both the network and the server.

When you need to perform many operations on the data in a specific table in the database, you can load the data into a temporary table while you modify it. Loading the data into a temporary table speeds up the process because all the operations are performed locally on the client.

Defining and Using a Temporary Table

You must define the temporary table before you can use it in your C/AL code. The variable that holds a temporary table is defined just like any other global or local variable.

To define a temporary table

  1. On the Tools menu, click Object Designer, and then create a new table.

    For information about how to create a table, see How to: Create a Table.

  2. Click View, and then click C/AL Globals or C/AL Locals, depending on whether your variable is going to be global or local.

    If you choose C/AL Globals, the C/AL Globals window appears.

  3. Enter a name for the temporary table variable, and enter or select Record as the data type. Use the lookup button in the Subtype field to select the table to copy.

  4. With the cursor still on the line that defines the temporary table, click View, and then click Properties (SHIFT+F4) to display the Properties window.

  5. Change the value of the Temporary property to Yes.

After you have created a temporary table, you can use it in your C/AL code. You can apply filters and perform searches just as you can with a database table.

See Also

Other Resources

Special C/SIDE Tables


C/SIDE System Tables

C/SIDE System Tables

System tables are stored in the database just like normal database tables. However, unlike normal database tables, they are created automatically. The information in system tables is closely related to the DBMS, which uses the system tables to manage, for example, system security and permissions in C/SIDE.

You can read, write, modify, and delete the information in system tables.

There are eight system tables in C/SIDE. The following six tables handle system security:

  • User System Table

  • Member Of System Table

  • User Role System Table

  • Permission System Table

  • Windows Access Control System Table

  • Windows Login System Table

The following two tables define data structure:

  • Company System Table

  • Database Key Groups System Table

Note Note

To insert, modify, or delete information in the User, Member Of, User Role, Permission, Windows Access Control, and Windows Login tables, you must have at least the same permissions as the users whose permissions you want to modify. This means that you can only assign or take away permissions that you yourself have.

See Also

Concepts

Security
Object-Level Security


User System Table

User System Table

The User system table gives you an overview of the user IDs with database logons that you have created for users in your database. Each record in the User table defines a single user ID.

The User table contains information about the password (displayed in encrypted form), the real name of the user, and how long the user's ID is valid for each user ID defined in your database. If you have the appropriate permissions, you can create new user IDs by entering the appropriate data in the User table. You can also remove a user ID by deleting the record from this table.

Expand image Deleting a Record

If you delete a record in the User system table, the corresponding entries in the Member Of system table are automatically deleted.

Expand image See Also

Reference

Member Of System Table

Concepts

C/SIDE System Tables


Member Of System Table

Member Of System Table

The Member Of system table gives you an overview of which role that each user is a member of and the company to which the role applies. Each user (ID) can be a member of multiple user groups.

Expand image See Also

Reference

User System Table

Concepts

C/SIDE System Tables


User Role System Table

User Role System Table

The User Role system table gives you an overview of the user roles in your database. A user role specifies a set of permissions. The exact permissions for each user role are defined in the Permission system table.

Expand image Deleting a Record

If you delete a record in the User Role system table, the corresponding entries in the Member Of and Permission system tables are also automatically deleted.

Expand image See Also

Reference

Member Of System Table
Permission System Table

Concepts

C/SIDE System Tables


Permission System Table

Permission System Table

You can use the Permission system table to define what different user roles are allowed to do. Permissions are specified for objects; so you can specify the exact set of permissions per table, form, codeunit, and so on. You can specify that a user role has no permissions (blank field), Full (Yes), or Indirect permissions to perform the following actions:

  • Read

  • Create/Insert

  • Modify

  • Delete

  • Execute

Setting the ObjectID to 0 applies the permissions for the role to all objects of the specified object type. For example, the ALL role in the Microsoft Dynamics NAV 2009 demo database company CRONUS has the permission Execute for the object type Codeunit and object ID 0. This means that the ALL role gives permission to execute all codeunits.

The Security Filter column is used to limit access by a role to fields in a table.

Expand image See Also

Concepts

C/SIDE System Tables
Permissions on Database Objects


Windows Access Control System Table

Windows Access Control System Table

You can use the Windows Access Control system table to manage the Windows access rights of a user or group of users, and thereby control their access to Microsoft Dynamics NAV. Each user or group Windows login has a unique security identifier (SID). In addition, each user or group has a role ID, which relates to a set of permissions within a certain company in Microsoft Dynamics NAV. The information displayed in the Login ID and Role Name fields is based on the login SID and role ID, respectively.

Expand image See Also

Reference

Windows Login System Table

Concepts

C/SIDE System Tables


Windows Login System Table

Windows Login System Table

You use the Windows Login system table to define which Windows users and groups can log on to the system. Only specified Windows users or members of a Windows group that is listed in the Windows Login table can log on. Each Windows user or group has a unique security identifier (SID). The name of the user or group that is displayed in the ID field is generated from the name of the user or group that is identified by the SID. The Name field is currently unused.

Expand image See Also

Concepts

C/SIDE System Tables
Windows Logins


Company System Table

Company System Table

The Company system table gives you an overview of the companies in your database. It contains a record for each company in your database. You can create a new company by entering a new record in this table. You can also delete a company from your database by deleting the record in the Company table.

When you delete a company, you delete all the tables in the company and all the permissions that include this company.

Expand image See Also

Concepts

C/SIDE System Tables
Dividing the Database into Companies


Database Key Groups System Table

Database Key Groups System Table

The Database Key Groups system table gives you an overview of the key groups defined in your database. Each record in this table shows a key group.

Note Note

By making your keys members of key groups, you can activate or deactivate various combinations of keys in your tables by enabling or disabling the key groups.

To enable and disable key groups

  1. On the File menu, click Database, and then click Information. The Database Information window appears.

  2. Click Tables and the Database Information (Tables) window appears.

  3. Click Key Groups and the Database Key Groups window appears.

  4. Select a key group and click Enable or Disable.

Expand image See Also

Concepts

C/SIDE System Tables
Key Properties
Table Keys


C/SIDE Virtual Tables

C/SIDE Virtual Tables

A virtual table contains information provided by the system. In C/SIDE, you have access to a number of virtual tables. They work in much the same way as normal database tables, but you cannot change the information in them. That is, you can only read the information. Another difference is that virtual tables are not stored in the database (as normal tables are) but are computed by Microsoft Dynamics NAV at run time.

Uses of Virtual Tables

Virtual tables give you a consistent interface to a variety of different information. Because a virtual table can be treated just like an ordinary table, you can use the same methods to access information in virtual tables as you use when you are working with ordinary tables. For example, you can use filters to get subsets or ranges of integers or dates.

The virtual tables provide such information as:

  • Integers in the range –1,000,000,000 to 1,000,000,000.

  • Dates within a given period.

  • Overview of the operating system files.

  • Overview of the logical disk drives.

  • Trace of database requests from your client to the database.

  • Overview of the users that are currently connected to the database.

  • Overview of the operating system files that store the database.

Types of Virtual Tables

C/SIDE contains numerous virtual tables, including Date, Integer, File, and Drive. Virtual tables such as Date and Integer give you easy access to data for use in applications.

Other virtual tables include:

  • Monitor

  • Session

  • Database File

  • Table Information

  • Field

  • Key

  • Server

  • Windows Object

  • Windows Group Member

  • SID - Account ID

  • User SID

A system administrator most commonly uses these latter virtual tables. They give the system administrator information about the users that are currently connected to the database and the current state of the system.

Because virtual tables are not stored in the database, you cannot view them directly. To view a virtual table, you must create a tabular form based on it.

To view a virtual table

  1. On the Tools menu, click Object Designer.

  2. Click Form, and then click New to open the New Form window.

  3. Select the Create a form using a wizard option and select Tabular-Type Form.

  4. In the Table box, enter the name of the virtual table that you want to base the form on. Alternatively, you can use the lookup button to select the table from a list of all the tables in the database. The virtual tables use the highest number range (2000000001 – 2000000203). This example uses the Date table, which is table 2000000007.

  5. Click OK and the Tabular-Type Form Wizard appears.

  6. Click the >> button to move all items in the Available Fields box to the Field Order box.

  7. Click Preview to view the table and its contents. Alternatively, click Finish and save the form.

See Also

Reference

Date Virtual Table


Date Virtual Table

Date Virtual Table

The Date virtual table gives you easy access to days, weeks, months, quarters, and years. The Date virtual table has the following fields.

Field | Description
Period Type | Days, weeks, months, quarters, or years.
Period Start | The date of the first day in the period.
Period End | The date of the last day in the period.
Period No. | The number of the period.
Period Name | The name of the period.

The following illustration shows the Date virtual table. For each period type, there are many records in the Date table.

You can apply filters to the Period Type, Period Start, and Period End fields to easily get a subset or range of days, weeks, months, quarters, or years to use in your forms or reports.

Expand image Date Virtual Table Example

The Date virtual table is most frequently used to provide a range of dates; the Receivables- Payables form is a typical example.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Integer Virtual Table

Integer Virtual Table

The Integer virtual table includes integers in the range –1,000,000,000 to 1,000,000,000. The Integer virtual table contains only one field.

Field | Description
Integer | An integer in the range -1,000,000,000 to 1,000,000,000.

By applying a filter to the Integer virtual table, you can easily get a subset or range of numbers that can be used to control looping in reports.

Expand image See Also

Concepts

C/SIDE Virtual Tables


File Virtual Table

File Virtual Table

The File virtual table gives you an overview of the files in a directory on your disk. The File virtual table contains the following fields.

Field | Description
Path | The filter on the Path field determines which directory is shown.
Is a File | The value Yes indicates that the entry is a file; the value No indicates that the entry is a directory.
Name | The name of the file or directory.
Size | The size of the file in bytes.
Date | The date the file was last modified.
Time | The time the file was last modified.
Data | A BLOB field with the contents of the file.

You must create a tabular-type form to access the File virtual table.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Drive Virtual Table

Drive Virtual Table

The Drive virtual table gives you an overview of the logical drives on your computer. The Drive virtual table contains the following fields.

Field | Description
Drive | The name of the drive, such as drive A or D.
Removable | Indicates whether the disk is removable (a floppy disk or CD-ROM) or a hard disk.
Size (KB) | The total size of the disk.
Free (KB) | The amount of free space on the disk.

You must create a tabular-type form to access the Drive virtual table.

Note Note

If there is no disk in your disk drive, the Size (KB) and Free (KB) fields will contain the value -1.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Monitor Virtual Table

Monitor Virtual Table

The Monitor virtual table traces all the database requests made by the client to the tables in your database. The Monitor virtual table is used by C/AL programmers to get an overview of the amount of time that specific operations take. C/AL programmers can use the information in this virtual table to optimize the performance of their code.

The Monitor virtual table contains the following fields.

Field | Description | Possible values
Entry No. | Successive numbers that are increased for each database. | From 1 to 231 -1.
Function Name | The type of database request. | LOCKTABLE, DELETE, MODIFY, INSERT, DELETEALL, Create Key, Delete Key, Redesign Table, FIND/NEXT, CALCSUMS, CALCSUMS (Slow), COMMIT, Delete Table, Create Database, Close Database, Open Database, Delete Database, Expand Database, Get Table Statistics, COUNT, Get Database Statistics, Optimize Key, Login, Read Database Block, Read BLOB, Insert BLOB, Delete BLOB, Clear Old Versions, Get Database Free Percent, Preload Database Block, and so on.
Parameter No. | The number of the parameter. | Depends on the number of parameters.
Parameter | The name of the parameter. | Table, Key, Order, Filter, Search Method, Search Result, Records Found, Sum, CPU (ms), Records Read, Sum Intervals, Records Deleted, Records Modified, Disk Reads, Disk Writes, Record, Wait, SumIndexFields, BLOB Field, Commit, User ID, File Name, Source Object, Source Trigger/Function, Source Line No., Source Text, Record Count, Timeout Status, Time Out (ms).
Number | If the parameter is a number, the value is shown in this column. | Any numeric value.
Data | Any nonnumeric parameter is shown in this column. | Any string.

To access the Monitor virtual table, click the Tools menu, and then click Client Monitor. The Client Monitor window opens.

The Client Monitor window has two tabs: General and Options. You use the Options tab to specify the kind of information that is collected by the Client Monitor.

Expand image Monitor Virtual Table Options

The Options tab contains the following parameters; the advanced parameters are only available in the SQL Server Option.

Parameter Behavior when selected

Include Object table activity

Every function that acts on the Object table is written to the Client Monitor.

Retain last source information

The parameters Source Object, Source Trigger/Function, Source Line No., and Source Line are written to the Client Monitor even for functions that are not related to the execution of C/AL code.

Show SQL statement

The SQL statement is displayed.

Use placeholders

The SQL statement uses ? placeholders instead of filter values.

Show server statistics

The following statistics are collected: Server Time, Logical Reads, and Records Read.

Show execution plan and SQL index

The SQL plan is displayed (for most statements), as a collapsed tree with the following format.

CopyCode image Copy Code
Plan Step(Object)[n,p];
// Here, node n has parent p.

For example:

CopyCode image Copy Code
Computer Scalar[2,1];Clustered Index Seek(User$0)[4,2]

This defines the following tree.

CopyCode image Copy Code
1 -- Root
---------2 -- Computer Scalar
------------------4 -- Clustered Index Seek(User$0)

The SQL index is also displayed as a list of fields in the same way as the Order parameter.

Show extended status information

The SQL status displays additional information:

  • Internal unique statement ID

  • Reuse status

  • Prepared status

  • Cursor type

  • Optimizer hints

  • Transaction type

Expand image See Also

Reference

Client Monitor - Additional Parameters for the SQL Server Option

Concepts

C/SIDE Virtual Tables


Client Monitor - Additional Parameters for the SQL Server Option

Client Monitor - Additional Parameters for the SQL Server Option
See Also
CollapseAll image

Some extra parameters are available on the Client Monitor to improve troubleshooting and performance analysis when you are running the SQL Server Option for Microsoft Dynamics NAV. These parameters can be configured dynamically and include status information about caching, SQL statements, and execution plans.

Collecting server statistics is time-consuming. If you are performing benchmarking to get the most accurate value for the Elapsed Time (ms) parameter, you should not collect statistics at the same time.

Similarly, displaying execution plans is extremely time-consuming and should not be done when you are benchmarking. This parameter is useful when you are troubleshooting problematic application areas to determine if a particular SQL statement is a bottleneck, and can be valuable to users who are unable to run the SQL Server Profiler tool.

Note Note

Executing a SQL statement in the SQL Query Analyzer to use its graphical execution plan does not necessarily give the same plan or statistics as when the same statement is executed from within Microsoft Dynamics NAV. This is due to cursor type differences. The SQL Server Profiler or the Client Monitor SQL Plan parameter gives the most accurate plan.

Expand image Monitoring Performance

Showing extended status information is useful when you want to see which properties of a SQL statement are being used in an operation. It is also possible to see how frequently statements are being reused or re-created. The unique ID can be used to cross-reference the statements that are being reused to determine the original SQL statement entry.

To use the Client Monitor to monitor server calls

  1. On the Tools menu, click Client Monitor to open the Client Monitor.

  2. Click the Options tab and select the parameters that you want to use.

  3. Click Start to activate the Client Monitor.

    You can close the Client Monitor window while you perform the tasks that you want to investigate.

  4. When you have completed these tasks, click Tools, and then click Client Monitor to open the Client Monitor window again.

  5. Click Stop to stop the Client Monitor.

Expand image See Also

Reference

Monitor Virtual Table


Session Virtual Table

Session Virtual Table

The Session virtual table gives you an overview of the users that are connected to Classic Database Server or to SQL Server.

The Session virtual table contains the following fields.

Field | SQL Server | Classic Database Server | Description
Connection ID | X | X | The ID of the connection.
User ID | X | X | The user ID of the connected user.
My Session | X | X | Whether a session belongs to you.
Login Time | X | X | The date when the user logged in.
Database Name | X | X | The name of the database that this session has opened.
Application Name | X | X | The name of the application connected to the server.
Login Type | X | X | Whether this session is a Windows login or a database login.
Cache Reads |  | X | The number of cache read operations performed by this session.1
Disk Reads |  | X | The number of disk read operations performed by this session.1
Disk Writes |  | X | The number of disk write operations performed by this session.1
Records Found |  | X | The number of records found since this session logged in.
Records Scanned |  | X | The number of records scanned by this session since user logged in.
Records Inserted |  | X | The numbers of records inserted by this session since user logged in.
Records Deleted |  | X | The number of records deleted by this session since user logged in.
Records Modified |  | X | The number of records modified by this session since user logged in.
Sum Intervals |  | X | The number of jumps between value intervals made by the system when calculating sums since this session logged in. A high value may indicate that an inefficient key is being used.
Host Name | X |  | The name of the workstation used by this session.
CPU Time (ms) | X |  | The cumulative amount of CPU time by this session.
Memory Usage (KB) | X |  | The number of kilobytes in the procedure cache that are currently allocated to this session.
Physical I/O | X |  | The cumulative amount of disk reads and writes for this session.
Idle Time | X | X | The amount of time that has passed since the server last received a database request from this session. If the field is empty, the session is currently performing a database request. This could be a long running database request, such as a table redesign.
Blocked | X |  | Whether this session is blocked (waiting to acquire a lock) by another session.
Wait Time (ms) | X |  | The amount of time that this session has been waiting.
Blocking Connection ID | X |  | The ID of the connection that is blocking this session.
Blocking User ID | X |  | The user ID of the connection that is blocking this session.
Blocking Host Name | X |  | The name of the workstation used by the connection that is blocking this session.
Blocking Object | X |  | The name of the SQL object that is blocking this session.

1 Only if Commitcache = Yes

Note Important

If an application solution uses any of the fields that are not available in the SQL Server Option for Microsoft Dynamics NAV, it must be modified to run on SQL Server. These fields will not be created on SQL Server. If the application tries to access them, an error message appears.

Expand image Using the Session Virtual Table

C/SIDE uses the Session virtual table to display database information.

To access the Session virtual table

  1. On the File menu, click Database, and then click Information. The Database Information window appears.

  2. Click the Sessions tab.

  3. Click the AssistButton in the Current Sessions field and the Database Sessions window (SQL Server Option) appears.

Note Note

Depending on which server option you are running, the Database Sessions window displays different fields from the Session virtual table

An administrator can terminate one of the sessions by selecting the session in question and deleting it. The user will then be disconnected from the server and will have to restart the program to continue working. To terminate a session, the administrator must have permission to delete data from the Session table.

In addition, for the SQL Server Option, the administrator must be a member of either the sysadmin or processadmin SQL Server server-level roles.

Note Note

On Classic Database Server, the terminated session will no longer take up any resources on the server.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Database File Virtual Table

Database File Virtual Table

The Database File virtual table gives you an overview of the operating system files that store the database. The Database File virtual table contains the following fields.

Field | Description
No. | The number of the operating system file.
File Name | The operating system file name.
Size (KB) | The size of the operating system file in kilobytes.
Total Reads | The number of read accesses since the database was opened.1
Mean Read Time (ms) | The average time for a read operation (in milliseconds).1
Reads In Queue | The number of read operations waiting in queue.1, 2
Total Writes | The number of write operations since the database was opened.1
Mean Write Time (ms) | The average time for a write operation (in milliseconds).1
Writes In Queue | The number of write operations waiting in queue (in milliseconds).1, 2
Disk Load (%) | A percentage weight describing the load on the disk.1

1 Not available in the SQL Server Option for Microsoft Dynamics NAV.

2 Only if Commitcache = Yes.

Note Important

If a solution uses any of the fields that are not available in the SQL Server Option for Microsoft Dynamics NAV, it will have to be modified to run on SQL Server. These fields will not be created on SQL Server. If the program tries to access them, an error message appears.

Expand image Viewing Database File Information

C/SIDE uses the Database File virtual table to show database information.

To access the Database File virtual table

  1. On the File menu, click Database, and then click Information. The Database Information window appears.

  2. Click the Database tab.

  3. In the Database Name field, click the AssistButton and the Database Files window appears.
Note Note

The Database Files window displays only some of the fields in the Database File virtual table. This window does not appear in the SQL Server Option.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Table Information Virtual Table

Table Information Virtual Table

The Table Information virtual table contains information about database tables. The Table Information virtual table contains the following fields.

Field | Description
Company Name | The name of the company the table belongs to.
Table No. | The ID number for the table.
Table Name | The name of the table.
No. of Records | The number of records in the table.
Record Size | A value expressing the average size of a record. Calculated as 1024 x Size (KB)/Records.
Size (KB) | How much space the table occupies in the database (in kilobytes).
Optimization | A percentage of Size that expresses how much data there is in a table. Some of the remaining size is used for internal administration in the table while the rest is slack-space. Slack-space can be minimized by optimizing the table.1

1Not available in the SQL Server Option for Microsoft Dynamics NAV.

Note Important

If a solution uses any of the fields that are not available in the SQL Server Option, it must be modified to run on SQL Server. These columns will not be created on SQL Server. If the program tries to access them, an error message appears.

To access the Table Information virtual table

  1. On the File menu, click Database, and then click Information. The Database Information window appears.

  2. Click Tables and the Database Information (Tables) window appears.
Note Note

The illustration shows the Database Information (Tables) table for the SQL Server Option. On Classic Database Server, this window contains an extra field and an extra button.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Field Virtual Table

Field Virtual Table

The Field virtual table contains information about fields in database tables. The Field virtual table contains the following fields.

Field | Description
TableNo | The ID number for the table.
No. | The number assigned to the field.
Table Name | The name of the table.
FieldName | The name of the field.
Type | The data type assigned to the field, for example, decimal.
Len | The length of the field entry in bytes.
Class | The class of the field, for example, FlowField.
Enabled | Whether the field is enabled.
Type Name | The data type assigned to the field. The length of the field entry in bytes is included for Code and Text data types.
Field Caption | The caption of the field in the language that has been selected.
RelationTableNo | The ID number for the table that the field is related to.
RelationFieldNo | The number of the field in another table that the field is related to.
SQLDataType | The data type assigned to code fields in the SQL Server Option.

You must create a tabular-type form to access the Field table.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Key Virtual Table

Key Virtual Table

The Key virtual table contains information about the keys that are defined in each table in the database.

The Key virtual table contains the following fields.

Field | Description
TableNo | The ID number for the table.
No. | The number of the key.
TableName | The name of the table.
Key | The fields that make up the key.
SumIndexField | The SumIndexFields that are defined for this key.
SQLIndex | The actual fields that have been defined in Microsoft Dynamics NAV and are used in the corresponding index on SQL Server instead of those defined in the key.
Enabled | Whether the index is enabled. This field can be modified.
MaintainSQLIndex | Whether the MaintainSQLIndex property has been activated. This field can be modified.
MaintainSIFTIndex | Whether the MaintainSIFTIndex property has been activated. This field can be modified.
Clustered | Whether the key is clustered. This field can be modified.

You must create a tabular-type form to access the Key table.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Server Virtual Table

Server Virtual Table

If you are running the SQL Server Option for Microsoft Dynamics NAV, you can access the Server virtual table.

The Server table contains the following fields.

Field | Description
Server Name | The name of the computer on which the server is installed.
My Server | Whether this is the server that you are logged on to.

You must create a tabular-type form to access the Server table.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Windows Object Virtual Table

Windows Object Virtual Table

The Windows Object virtual table gives you an overview of the Windows users and Windows groups that can be integrated into the Microsoft Dynamics NAV security system. You can see this information when Microsoft Dynamics NAV is running on a client that is Active Directory-enabled. Microsoft Dynamics NAV retrieves the data from Active Directory.

The Windows Object virtual table has the following fields.

Field | Description
GUID | The globally unique identifier (GUID) for the Windows user or group.
ID | The ID of the Windows user or the Windows group. This information is displayed in the User ID fields of the User and Member Of system tables.
Name | The name of the Windows object. This object can be a Windows user or a Windows group. The object name is displayed in the Name field of the User system table and in the User Name field of the Member Of system table.
Type | Whether the object is a Windows user or a Windows group.
SID | The unique security identifier (SID) of the Windows user or group.
Distinguished Name | Identifies the domain that holds the Windows object as well as the complete path to the object. Every object in the Active Directory has a unique distinguished name.

You must create a tabular-type form to access the Windows Object table.

Expand image See Also

Concepts

C/SIDE Virtual Tables


Windows Group Member Virtual Table

Windows Group Member Virtual Table

The Windows Group Member virtual table contains information about the members of Windows Groups who can be integrated in the Microsoft Dynamics NAV security system. A Windows group member who has permissions in the Microsoft Dynamics NAV security system does not have to enter a password when the member logs on to Microsoft Dynamics NAV.

You can see this information when Microsoft Dynamics NAV is running on a client that is Active Directory-enabled. The Windows Group Member virtual table contains the following fields.

Field | Description
Group GUID | The globally unique identifier (GUID) of the Windows group.
Member GUID | The GUID for the Windows group member.
Group ID | The ID of the Windows group to which the Windows group member belongs.
Member ID | The ID for the Windows group member.

You must create a tabular-type form to access the Windows Group Member table.

Expand image See Also

Concepts

C/SIDE Virtual Tables


SID - Account ID Virtual Table

SID - Account ID Virtual Table

The SID - Account virtual table can convert the security identifier (SID) of a Windows object into an ID. It can also convert the ID of a Windows object into a SID. The Windows object can be a Windows user or group. The ID is calculated on the basis of the SID.

If you request a record with a specific SID, the SID - Account ID virtual table is searched and an ID is returned.

The SID - Account ID virtual table has the following fields.

Field | Description
SID | The security identifier (SID) of the Windows user or group.
ID | The ID of the Windows user or group. The ID is calculated on the basis of the SID.
Note Note

The SID - Account ID table will always appear to be empty.

You must create a tabular-type form to access the SID - Account ID table.

Expand image See Also

Concepts

C/SIDE Virtual Tables


User SID Virtual Table

User SID Virtual Table

The User SID virtual table shows the security identifiers (SIDs) and IDs of the groups that the user, who is logged on to the system, is a member of. The User SID virtual table has the following fields.

Field | Description
SID | The security identifier (SID) of the groups that the user is a member of.
ID | The ID of the groups that the user is a member of. The ID is calculated on the basis of the SID.

You must create a tabular-type form to access the User SID table.

Expand image See Also

Concepts

C/SIDE Virtual Tables