Application Designer’s Guide

This publication is subject to change without notice and does not

represent any commitment on the part of Navision Software a/s.

Navision Software a/s assumes no responsibility for any faults or

shortcomings in this publication.

The software described is supplied under license and must be used

and copied in accordance with the enclosed license terms and
conditions.

According to existing Danish copyright legislation, it is against the

law to reproduce any part of this publication in any form or by any
means, without the permission of Navision Software a/s.

Navision is a registered trademark, and AssistButtons, C/AL,

C/SIDE, FlowField, FlowFilter, SIFT, SumIndex and SumIndexField are
trademarks of Navision Software a/s.

Microsoft, Windows and Windows NT are trademarks of Microsoft

Corporation.

OS/2 is a registered trademark of the International Business

Machines Coporation.

Paintbrush is a registered trademark of Zsoft Corporation.

The MetaPlus font was used.

Copyright © 1996 Navision Software a/s. All rights reserved.

ISBN 87-7849-063-4
Doc. no. W1-XA-BAF1-CB08-O

Published by Navision Software a/s.

Preface

This book is a manual for the C/SIDE development system. It is part of a

comprehensive set of documentation and help materials for the Navision
Financials accounting and business management solution.

It is assumed that you are comfortable with using Microsoft Windows and the
user interface of Microsoft Windows applications. If not, you should consult
the Microsoft Windows documentation.

The manual is divided into parts. When you create a C/SIDE application you
combine five types of application objects into a whole that solves a business
problem. Each of the five types of application objects has its own part in the
manual. The order in which the parts appear corresponds to the order in which
you are most likely to need them when you design a new application. That is,
the part dealing with tables comes before the part dealing with forms, as you
should design your tables before you design forms.

Each part contains one or more chapters. The first chapter in a part always
deals with the fundamentals, for example ‘Form Fundamentals’, and the
succeeding chapters present more advanced information.

Each chapter starts with a short introduction and an overview of the chapter
contents. This makes it possible for you to quickly decide whether this chapter
is the place to find the information you need.

In addition to this printed manual, C/SIDE has an online Reference Manual.

There you will to find reference information about programming issues:
functions, triggers, properties, and so forth.

Your software package comes with three printed manuals for the accounting
and business management part of the program:

Navision Financials User’s Guide. This book is designed to serve as a

reference work in which you can look up information that will help you perform
concrete tasks with Navision Financials. The User’s Guide has a task-oriented
approach, so it does not cover every detail of Navision Financials. If you need
to find out more about certain fields or windows that are not described in the
Users’s Guide, you can use online Help, which offers guidance to all the fields,
tables, windows, menus, reports and batch jobs in the program.
Introduction to Navision Financials. Here, you will find an overview of what
the program contains, what it can do, and how it works.

Navision Financials Installation and System Setup. This manual explains the
more technical aspects of Navision Financials. You will find information about
user administration, backup procedures and other items that are also relevant
for application developers.
Table of Contents

Part 1 Fundamentals
Chapter 1 C/SIDE Fundamentals 3
The C/SIDE User Interface 4
What Is a C/SIDE Application? 8
The Physical and the Logical Database 11

Chapter 2 Designing a C/SIDE Application 13

Introduction to C/SIDE Application Design 14

Part 2 Tables
Chapter 3 Table Fundamentals 23
What Is a Table? 24
What Are Keys? 30
Saving, Viewing, and Sorting Data 37
Dividing the Database into Companies 40
Special Table Fields 42

Chapter 4 Customizing and Maintaining

Tables 51
Viewing and Modifying Properties 52
Using Table and Field Triggers 59
Setting Relationships Between Tables 61
Changing Tables That Contain Data 66

Chapter 5 Special C/SIDE Tables 67

What Is a Temporary Table? 68
What Is a System Table? 71
What Is a Virtual Table? 76
Overview of C/SIDE Virtual Tables 77

Part 3 Forms
Chapter 6 Form Fundamentals 89
What Are Forms? 90

i
 Contents

Creating Forms 93
Selecting, Moving and Adjusting Controls 100
Saving, Compiling and Running Forms 106

Chapter 7 Designing Forms 109

Form and Control Properties 110
Types of Controls 113
Adding Controls 115
Tools for Customizing Controls 119
Setting Control Properties 121
How to Use Controls in Applications 126

Chapter 8 Extending the Functionality of Your Forms 139

Main Forms and Subforms 140
Looking Up Values and Validating Entries 144
Drilling Down to the Underlying Transactions 150
Launching Another Form 152
Designing Menu Buttons 153
Form and Control Triggers 158

Part 4 Reports
Chapter 9 Report Fundamentals 165
What Are Reports? 166
What Happens When a Report Runs? 171
The Report Designer 175
Saving, Compiling and Running Reports 179

Chapter 10 Designing Reports 183

Report Properties 184
Designing a Simple Report 188
Designing a More Advanced Report 197

Chapter 11 Extending the Functionality of Your Reports 203

Grouping and Totaling 204
Triggers in Reports 212
Advanced Sample Reports 214

ii
 Contents

Part 5 Codeunits
Chapter 12 Codeunit Fundamentals 235
What Is a C/SIDE Codeunit? 236
Creating Codeunits 238
Using Codeunits 246

Chapter 13 Introducing the C/AL Language 249

What Can You Do with C/AL? 250
What Are Statements, Expressions, and Operators? 251
Introducing the Elements of C/AL Expressions 258
The C/AL Control Language 268

Chapter 14 Using C/AL 277

Overview 278
System-Defined Variables 280
Handling Run-Time Errors 281
The Essential C/AL Functions 282

Chapter 15 C/AL Debugging 297

What Are Bugs? 298
Syntax Errors 299
Run-Time Errors 301
Program Logic Errors 307
The C/SIDE Debugger 310

Part 6 Appendixes
Appendix A C/SIDE Specifications 323
Specifications for the DBMS 324
Specifications for C/SIDE Application Objects 325

Appendix B Type Conversion 327

Type Conversion in Expressions 328
Type Conversion Mechanisms 330

Appendix C SumIndexFields 339

What Is a SumIndexField? 340

Appendix D C/SIDE in Multiuser Environments 343

Ensuring Data Integrity in a Multiuser Environment 344

iii
 Contents

Appendix E Performance 355

The DBMS Cache 356
The Commit Cache 358
The Command Buffer 360

Appendix F Report Flow Charts 363

Report Flow charts 364
Report.Run 365
DataItem.Run 366
Section.Run 367
Header.Run 368
Footer.Run 369
TransHeader.Run 370
TransFooter.Run 371
GroupHeader.Run 372
GroupFooter.Run 373
Body.Run 374
NewPage 375
GetRecord 376

iv
Part 1
Fundamentals
Chapter 1
C/SIDE Fundamentals

A C/SIDE application is composed from five types

of application objects. Each type of application
object is created using a specific tool called a
designer. 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.

This chapter introduces you to the C/SIDE user

interface and presents the general concepts that
underlie C/SIDE application objects.

· The C/SIDE User Interface

· What Is a C/SIDE Application?
· The Physical and the Logical Database
 Chapter 1. C/SIDE Fundamentals

1.1 The C/SIDE User Interface

This section introduces you to the user interface in C/SIDE. If you have not
already installed C/SIDE, refer to the installation manual. If you have already
installed C/SIDE, the installation program has created a new group that
contains all the icons you need to work with C/SIDE. When the Integrated
Development Environment (IDE) is running, your screen will look like this

The title bar

The menu bar

The toolbar

The work area

The status bar

The user interface gives you access to a number of tools and functions. Some
parts of the user interface also provide information about the current state of
the system. The table below explains when to use the most important parts of
the C/SIDE user interface.

To... Use the...

get information about the name and path of the current database title bar
access functions on drop-down menus menu bar
access the most commonly used functions quickly toolbar (A)
work with the application design tools work area(B)

4 The C/SIDE User Interface

 Chapter 1. C/SIDE Fundamentals

To... Use the...

see basic status information about your system (such as the current status bar
date and your user ID)

(A) Depending on the task you are working on, the system automatically changes the
icons.
(B) This is also where the user interacts with your applications.

Designing Application Objects

Any application designed in C/SIDE is based on five different types of
application objects:

Tables are the Tables are the fundamental objects that store the actual data; you need other
fundamental objects application objects to insert, modify, delete or show data from tables. You will
that store the actual data
typically will use a form to enter or retrieve data from the database and use a
report to print data.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
all application objects are identified by an ID number. There are, however,
restrictions about which numbers you should use when you create your own
application objects. Please contact your NTR for more information.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The main tool used for developing applications in C/SIDE is the Object
Designer (choose Tools, Object Designer). This is the tool you use to view and
design tables, forms, reports, dataports and codeunits.

The C/SIDE User Interface 5

 Chapter 1. C/SIDE Fundamentals

The Object Designer

gives access to all
other application
object designers

In the Object Designer you choose the type of application object you want to
work on. From the Object Designer you can run an application object or start an
application object designer to modify the design of an existing application
object or create a new application object. The following picture shows how to
use the Object Designer in more detail.

6 The C/SIDE User Interface

 Chapter 1. C/SIDE Fundamentals

This is where you

access the
designers for
different objects.
You simply choose
the type of object
you want to work on
here.

Create a new object

Change the design of
the current object
Run the current object

The Object Designers The table below lists the tools you can access via the Object Designer and
when you should use them.

Use the... When working on ...

Table Designer tables
Form Designer forms
Report Designer reports
Dataport Designer dataports
C/AL editor codeunits
As you can see, there is a specific designer for each type of application object.
When you create or modify an application, you can work on any number of
application objects at the same time, and each application object is shown in
its own designer. For example, if you work on three new forms at the same
time, then each form will be displayed in its own form designer. The only
designer that you cannot create more than one copy of is the Object Designer.
You will learn more about how to use each of these designers as you read the
following parts of this book.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
there is no access to the DataPort Designer in this version.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The C/SIDE User Interface 7

 Chapter 1. C/SIDE Fundamentals

1.2 What Is a C/SIDE Application?

The C/SIDE Integrated Development Environment (IDE) is specially designed
for creating accounting and business management applications. Any C/SIDE
application consists of the same objects as a C/SIDE database. The difference
between the term database and the term application is that when we speak
about a database, we mean simply a collection of application objects, whereas
when we speak about an application, we mean a set of application objects tied
together to form a coherent whole.

General C/SIDE Concepts

You have already learned that there are five different types of application
objects in C/SIDE. All five types are based on some general concepts. Some of
these concepts are restricted to one type of application object while others
apply to several types. When you understand these fundamental concepts, you
have a good foundation for creating your own applications. The figure below
illustrates how the application objects are related to these general concepts.

8 What Is a C/SIDE Application?

Chapter 1. C/SIDE Fundamentals

The table below summarizes the information in the figure, and explains what
each type of application object is used for.

Application What is it used for? Which concepts is it

Object Type based on?
Table A table is used for storing the actual data. Typically a Properties, Fields,
business application will have a Customer table that Keys, C/AL
stores information such as name, address, phone
number and contact person for each of your customers.
Form A form is used to access the information in your tables. Properties, C/AL,
Forms are used both when you enter new information Controls
and when you view existing information.
Report A report is used to present data that contains summary Properties, C/AL,
information. For example, you will use a report to print a Controls, DataItems,
list of customers. Sections, Templates,
RequestForm
Dataport A dataport is used to import and export information to Properties, C/AL,
and from other programs (a comma-separated file from a DataItems,
spreadsheet, for example). RequestForm
Codeunit A codeunit contains user-defined functions written in C/AL
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 over
and over again.
The terms in the third column have the following descriptions:

Properties Properties control the appearance and behavior of application

objects and all subobjects. Properties are used to control the appearance of
data, specify default values, specify colors and define relationships.

C/AL C/AL is the language used for writing functions in C/SIDE. In the table
above, ‘C/AL’ refers to functions written in this language.

Triggers When specific things happen to the application objects, the system
automatically activates a trigger. Inside a trigger you can add your own C/AL
code if you want to modify the default behavior of the application object or
extend its functionality.

Keys A key defines the order in which data are stored in your tables. You can
speed up searches in your tables by defining several keys which sort your
information in different ways.

Fields A field is the smallest unit of information in your database. A field

typically stores information such as a name or a number.

What Is a C/SIDE Application? 9

Chapter 1. C/SIDE Fundamentals

Controls Controls are objects on a form or report that display data, perform
actions or decorate the form. Typical examples are 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 appears 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 you use for defining a model of
your data when you create a report. By using a hierarchy of data items you
define which data your report should include. 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. A section is where you

place controls to display information. You will typically use sections defining
the body, header, and footer in your report.

10 What Is a C/SIDE Application?

 Chapter 1. C/SIDE Fundamentals

1.3 The Physical and the Logical Database

The previous section described the general concepts underlying all five types
of application objects in C/SIDE. This section presents another view of C/SIDE
applications. In this view we are concerned only with how the information in
your application is structured.

As a typical database user, you are not concerned with where each piece of
data is stored on the hard disk or what its size 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 you with a conceptual
representation of data that does not include too many details of 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 relations) which are easier to understand.

This leads us to distinguish between the logical and the physical database.
When we speak about the logical database we are concerned only with the
structure of the data and the relationships between different bits of
information. That is, we do not deal with how these structures and relations
are implemented. When we speak about the physical database we deal only
with how the structures in the logical database and the search paths between
them are implemented.

In this book the term database should be interpreted to mean the logical
database unless otherwise noted.

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 figure below illustrates how one logical database can be
physically stored on three hard disks but still comprise a single (logical)
database.

One logical Several physical

database disks files
Logical = Physical + Physical + ... + Physical
Database Disk File Disk File Disk File

The Physical and the Logical Database 11

 Chapter 1. C/SIDE Fundamentals

The Logical Structures in Your Database

Access to the data is made possible by a well-defined logical organization
composed of:

Fields A field is the smallest logical structure used in the C/SIDE database. A
field is used to hold a single bit of information, such as a name, ‘Joe,’ or an
amount, ‘2,352.00.’ Any particular field can hold information of only one
specific type. (The C/SIDE database system distinguishes between 10 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. By assembling these small bits of information into records we get
a much more flexible ‘information-holder’ that is also better organized because
it keeps together fields that belong together.

Records A record is a logical structure assembled from an arbitrary number of

fields. It is used to store a single entry in the database. The fields in a record
are used to 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 used in a C/SIDE

database. A company may be considered as a subdatabase; its primary use is
to separate and group large portions of data in a database. A company can
contain private tables as well as tables shared with other companies.

Database
Companies are the
largest logical Company
structures in a C/SIDE Table
database Record

Field
Fields are the
smallest logical
structures in a C/SIDE
database

12 The Physical and the Logical Database

Chapter 2
Designing a C/SIDE Application

Carefully planning the details of your database

applications will help you end up with a sound
design. A properly designed application is easier
to build and maintain.

This chapter provides guidelines for creating

quality applications in C/SIDE using the well-
known methodology of analysis, design, and
implementation.
 Chapter 2. Designing a C/SIDE Application

2.1 Introduction to C/SIDE Application Design

In this section we will briefly outline the procedures involved in designing a
C/SIDE database application. It usually includes the following steps:

Understanding the Problem Make sure you understand the business

problem you are trying to solve. Be sure you know who will be using the
application and what they will be trying to accomplish.

Designing the Tables Begin by designing a data model that you use to
determine how the data will be stored and how it can be most meaningfully
utilized. The data model determines:

· which tables the database must contain.

· what kind of data you want to store in the fields in the tables.
· 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 completed the design of the
database tables, you are ready to begin designing the application itself. This
involves:

· designing forms (to enter and retrieve data) and reports (to retrieve and
present data).
· creating C/AL code to connect the application objects.
The above steps depend on each other. When you go from one step to another
you will often have to rethink some of the decisions you made in the previous
step.

Understanding The Problem

To decide which information you should store in C/SIDE, you have to
determine the purpose of the database and how it will be used. The easiest
way to do this is to talk to the people who will use it. Involving the end user as
early as possible eliminates problems that can stem from misunderstandings
about the purpose of the database. Interviewing the end users will help you
get a better understanding of the tasks they expect the system to be able to
solve. Based on this, you can determine the data (tables) necessary for
completing these tasks. This will often be the most difficult part of the design

14 Introduction to C/SIDE Application Design

 Chapter 2. Designing a C/SIDE Application

process–and also the most important, as the usefulness of the entire

application depends on whether the tables have been designed correctly.

Your interviews of the end users will give you a good knowledge of which
questions the end users want answered and thus of the information that forms
and reports should provide. This does not necessarily tell you how you should
structure your tables, however.

Designing the Tables

Your next task is to divide the information you want to store in the database
into basic categories such as customers, products, employees, and so on.

You begin by defining a data model. This model should describe:

· the tables in the database.

· the fields in the tables.
· the relations between the fields in your tables.
· constraints for fields and relations.
A model suitable for this purpose is the ER model (Entity-Relationship model).
An ER model is capable of mapping real-world situations to a relational
database system such as C/SIDE.

Basically, an ER model divides all the elements of a real world situation into
two categories: entities and relations. 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 will complete the following steps:

1 Identify the types of entities associated with your problem. Create tables to
represent each of these types of entities.

2 Identify the properties of each entity type 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.

Introduction to C/SIDE Application Design 15

 Chapter 2. Designing a C/SIDE Application

The following subsections are not intended to serve as a description of all

facets and implications of the ER model but are rather intended to give you an
overview of the model and at the same time show you the benefits of applying
a formalized design method.

How Are ER Model Concepts Related to C/SIDE Concepts?

A real world problem will usually contain groups of entity types that are similar.
For example, consider a company having 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, that is, a set of entities that have the same properties.
When you implement the abstract ER model in C/SIDE, you will 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 table below 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

Determining Field Types

In the ER model, after you have identified the entity types and their properties,
your next step is to determine the types of values these properties can have. In
C/SIDE this corresponds to determining the data types of the fields in your
tables.

Example

Suppose that your analysis using the ER model has revealed that you have an entity type describing
your company’s customers. This has led you to define a Customer table:

16 Introduction to C/SIDE Application Design

 Chapter 2. Designing a C/SIDE Application

Customer Table Company Name Contact Person Phone ... Payment Method

...

...

...

...

...
Your analysis has shown that you need fields such as Company Name, Contact Person, Phone and
Payment Method. When you implement the Customer table, you select the following field types:

Field Name Description Field Type

Company Name This field is used to store the name of the string
customer (for example ‘Navision Software’).
Contact Person This field identifies the contact person in the string
company (for example ‘JLJ’).
Phone This field contains the customer’s phone string
number (for example ‘45662111’).
Payment Method This field describes the payment method for option
the customer (for example ‘pay in cash’).
Refer to Choosing Data Types on page 27 for a description of the C/SIDE field types.

Role of Keys in C/SIDE

The ER model places a very important constraint on the entities in an 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 whose
values are distinct for each individual entity. The table below shows how the
ER model concepts are related to C/SIDE concepts

ER-Model Concept Corresponding Concept in C/SIDE

Constraints on the entities of a entity type Constraints on the records in a table
The uniqueness constraint on entity properties A key based on fields in a table
For C/SIDE to be able to operate efficiently on the data in tables, the records
must be arranged according to some criterion (that is, a key). For example, an
Employee table can be ordered according to the employees’ social security
numbers because this number uniquely identifies each employee.

In order for a field to be a key for a table, the uniqueness constraint above
must hold for every record in the table. This constraint prevents any two
records from having the same value for the key field. It is not a constraint on a
specific record but a constraint for all records in the table, considered together.

Introduction to C/SIDE Application Design 17

 Chapter 2. Designing a C/SIDE Application

Sometimes a key consists of several fields together; in this case the

combination of the field values must be distinct for each record.

Sometimes you will be able to define several keys for a table. Refer to the
section How to Define a Primary Key on page 30, which discusses the concepts
of keys.

Determining the Relationships

At this point in the design process, you have carefully planned a number of
tables to store individual types of information. In your final application you
want to be able to retrieve the information in a meaningful way. Very often an
answer from your database will consist of information stored in several tables.
To allow for such answers, C/SIDE uses relationships to chain related
information together. In database terminology it is common to distinguish
between three types of relationships:

One-to-Many Relationships In this type of relationship, a record in Table 1

can have more than one matching record in Table 2, while 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 this type of 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 this type of 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 simply be avoided by combining the two tables.

Assuring the Quality of the Design

In the process of defining the tables and setting up relationships, you will often
have to select from among several possible solutions. To make sure that you
select the most appropriate solutions, you need a way to measure design
quality.

This is done using what is known as the normalization process. The

normalization process takes your design through a series of tests to verify
whether it belongs to a certain normal form. There are six normal forms. Most

18 Introduction to C/SIDE Application Design

 Chapter 2. Designing a C/SIDE Application

texts on relational database design can teach you how to obtain these normal
forms. Some good starting points are the books mentioned on the last page of
this chapter.

Designing the Application

After you have completed your table design, you are ready to begin designing
the application itself. From the analysis phase, you have an overview of which
answers the application is expected to be able to provide. From the table
design phase, you have a clear description of where and how the information
will be stored. Based on this understanding, you are ready to begin assembling
the entire application.

This part of the application design involves:

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.

Reports allow more flexibility than forms do when you want to present
summary information.

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 normally an iterative
process.

At this point you will have a useful application. If you took the time to plan all
steps of the application design carefully, you also have an application that is
fully documented. This will prove to be a great help when you need to make
future adjustments and additions.

Recommended Books on Database Design

Some of the most well-known books about relational database design are:

C. J. Date. An Introduction to Database Systems. Addison-Wesley Publishing

Co.

Introduction to C/SIDE Application Design 19

Chapter 2. Designing a C/SIDE Application

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.

20 Introduction to C/SIDE Application Design

Part 2
Tables
Chapter 3
Table Fundamentals

Tables are the fundamental objects in any

database. This is true no matter what kind of data
you need to store. When you create a new
database, you begin by building the tables. Later
on, you create forms and reports in order to
access and view the data in the tables.

This chapter explains how to design appropriate

tables to store your data.

· What Is a Table?
· What Are Keys?
· Saving, Viewing, and Sorting Data
· Dividing the Database into Companies
· Special Table Fields
 Chapter 3. Table Fundamentals

3.1 What Is a Table?

The records in the C/SIDE database are stored in tables. A C/SIDE table may be
visualized as a two-dimensional matrix, consisting of columns and rows. The
figure below shows a table with nine rows and eight columns. Each row is a
record, and each column is a field.

Columns: Fields

Rows: Records

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 next figure illustrates how the
table data and the table description together form a table.

Table This is the Table

- Properties Description
- Triggers
- Keys

Table Data

When you design a table, you assign it a number of characteristics, 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

24 What Is a Table?
 Chapter 3. Table Fundamentals

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 figure illustrates that a table description contains properties, triggers,

fields and keys and shows how these are related.

Table description

Table Properties

Triggers

Fields Properties
Triggers
Keys Properties
The table description contains some properties that are related to the table,
while others are related the fields in the table. Still other properties are related
to the keys in the table. You can also see from the figure that triggers are
defined both for the table and for the fields in the table.

Don’t worry if you are not familiar with these terms already. You’ll learn more
about them on the following pages, and the next chapter, Customizing and
Maintaining Tables on page 51, provides a more detailed description of how to
customize your tables by modifying the properties and creating triggers.

Creating a Table
When you first create a table, it will not contain any data. When you create the
table you have to decide which types of information you want to store in it.

What Is a Table? 25
 Chapter 3. Table Fundamentals

To create a table:

1 From the View menu, choose Object Designer. C/SIDE will display:

Select the type of

object you want to
work on here

Create a new object

2 In the Object Designer, click the Table button.

3 Click the New button. C/SIDE will show the Table Designer

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. The
following subsections describe how to do this.

26 What Is a Table?
 Chapter 3. Table Fundamentals

Adding Fields to Your Table

Designing a field means assigning it a number of characteristics. These
characteristics depend on what you intend the field to be used for.

After you have added fields to a table in the Table Designer, you must save the
table before you can add any records. Once you have saved a table, it will
appear in the list of tables in the Object Designer.

All the tables and fields you create have two forms of identification:

· A unique identification number (integer). When you access your database

using either the C/SIDE IDE or C/FRONT, this number uniquely identifies all
tables and fields.
· A name (an alphanumeric string) serving as a label (such as CUSTOMER or
CITY). This name appears on the screen when you run the table and should
be meaningful and easily understood. This name is secondary information
and can be changed at any time.

Choosing Data Types

When you have selected an identification number and name for a field, you
have to select an appropriate data type. You can use 10 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:

What Is a Table? 27
Chapter 3. Table Fundamentals

Data Type Description Size

option Denotes an integer in the range -2,147,483,647 and 2,147,483,647. An 4 bytes
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. An 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".
integer Denotes an integer between -2,147,483,647 and 2,147,483,647. 4 bytes
decimal A decimal number between -1063 and 1063. The exponent ranges from 12 bytes
-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).
text Any alphanumeric string. The field must be defined to be between 1 Maximum
and 250 characters. The space used by a text field equals the string length +
maximum length of the text plus one byte. This extra byte is a used to 1 byte (see
hold the length of the string. An empty text string has the length zero. note below).
code An alphanumeric string, which is right-justified if the contents are Maximum
numbers only. If letters or blanks occur among the numbers, the string length +
contents are left-justified. All letters are converted to uppercase upon 2 bytes (see
entry. note below).
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.
date A date value in the range from January 1, 0 to December 31, 9999. An 4 bytes
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..
time Any time in the range 00:00:00 to 23:59:59.999. A time field contains A time field is
the value: 1 plus the number of milliseconds since 00:00:00 o'clock, or stored as an
0. Time = 0 is an undefined time. A time value is calculated in the integer (four
following way: bytes).
Time = 1 + (number of milliseconds since 00:00:00).
boolean Assumes the values TRUE or FALSE. When formatted, a boolean field 4 bytes
is shown as "Yes" or "No".
binary Contains binary data. The binary data is stored in the record. 2000 bytes
(see note
below).

28 What Is a Table?
Chapter 3. Table Fundamentals

Data Type Description Size

BLOB Binary Large Object. Used to store bitmaps and memoes. 8 bytes in the
Notice that the BLOB isn’t stored in the record, but in the BLOB area of record + size of
the table. BLOB data.
(max. 2 GB)

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
data is stored with a four byte alignment because of performance
considerations. 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.
This means that, for example, a text string of 10 characters will occupy 12
bytes.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Besides the ordinary fields discussed in this section, the C/SIDE database
system also includes two special types of fields

· FlowFields
· FlowFilters
How these special fields provide powerful data retrieval mechanisms is
described in the section Special Table Fields on page 43.

What Is a Table? 29
 Chapter 3. Table Fundamentals

3.2 What Are Keys?

The DBMS keeps track of each field by means of the field number, described
above, 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, the records are stored sequentially in ascending order, sorted

according to the primary key. Before adding a new record to a table, the DBMS
checks that the information in primary key fields in the record is unique, and
only then inserts the record into its correct logical position. Because the
records are sorted ‘on the fly,’ the database will always be structurally correct.
This allows 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; 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. Be aware that
it is not the value in each field in the primary key that must be unique, but
rather the combination of values in all the fields comprising the primary key.

Some other database systems support unkeyed tables. An unkeyed table is

one for which no key fields have been designated; in such a table, records are
stored in the order in which they were entered in the table. The C/SIDE
database system does not support unkeyed tables.

How to Define a Primary Key

A maximum of 20 distinct fields can be used in the definition of the primary
key. The number of fields in the primary key puts a limitation on the number of
fields in the other (secondary) keys.

When you create a table in the table designer, C/SIDE automatically uses the
field with the lowest field number as primary key.

30 What Are Keys?

 Chapter 3. Table Fundamentals

To define a primary key:

1 Assume that you have created a table in the Table Designer:

2 Choose Keys from the View menu to define a primary key. C/SIDE will
display the following:

Define the primary

key here

3 On the first line in the Key window, enter the primary key as a comma-
separated list (for example: ID Number,Name).

How to Create Secondary keys

We have already mentioned that up to 40 keys can be associated to a table and
that the first is the primary key. All other keys are secondary keys and optional.
Secondary keys are used to view records in an order different from the one in
which they are sorted according to the primary key fields.

What Are Keys? 31

 Chapter 3. Table Fundamentals

To create a secondary key:

1 Open your table in the Table Designer:

2 Choose Keys from the View menu to define secondary keys. C/SIDE will
display the following:

Enter the
secondary keys
here as comma-
separated lists.

3 The first line shows the primary key. Enter the secondary keys on the
following lines as comma-separated lists (for example: Name,Address).

Notice that ...

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
the number of fields in the primary key together with all the fields in secondary
keys must not exceed 20.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
This means that if your primary key includes four distinct fields, then your
secondary keys can include these four fields, and at most 16 others.

32 What Are Keys?

Chapter 3. Table Fundamentals

Correspondingly, if your primary key consists of 20 distinct fields, then your

secondary keys must consist only of combinations of these fields.

A secondary key uses an additional data structure called an index. The idea
behind an index is similar to the idea behind the indexes used in common
textbooks. A textbook index lists important terms at the end of the book in
alphabetical order. Next to each term is a list of page numbers where the term
appears. We can search the index to find a list of page numbers (addresses)
and easily locate the term in the textbook by searching the specified pages.
Hence, the index is an exact indicator of where each term occurs in the
textbook.

When you define a secondary key and mark it as active, the system will
automatically maintain an index reflecting the sorting order defined by the key.
Several secondary keys may be active at the same time.

A secondary key can be changed into an inactive key. This means that the
DBMS does not use time during updates to maintain its index. Furthermore, an
inactive key doesn’t occupy database space.

Inactive keys can be reactivated; this process may consume some time,
depending on the size of the table, because the DBMS has to scan the entire
table to rebuild the index.

The fields comprising the secondary keys are not guaranteed to contain unique
data; 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, the DBMS will use the primary key for the table to solve this conflict. The
example below shows how the primary key influences the sorting order when a
secondary key has been activated:

We assume that the Customer table includes four entries (records). The
records in the Customer table have two fields: Customer No. and Customer
Name. The Key List for the Customer table is:

Key No. Key Type Definition

1 Primary Customer No.
2 Secondary Customer Name

What Are Keys? 33

 Chapter 3. Table Fundamentals

Customer table sorted by the primary key:

Customer No. Customer Name

001 Navision
002 IBM
003 Lotus
004 Navision

If you select the secondary key for sorting, the ordering will be based on the
contents of the Customer Name field. As the contents of these fields are not
unique, the records will have to be subsorted according to the primary key.

Customer Name Customer No.

IBM 002
Lotus 003
Navision 001
Navision 004

In this case the last two records, which have the same Customer Name, have
been ordered by Customer No.

How Keys Affect the Working Speed of C/SIDE

Searching for specific data is normally easier if several keys have been defined
and maintained for the table holding the desired data. The indexes for each of
the keys provide specific views that enable flexible searches to be performed
quickly. There are, however, both advantages and drawbacks to using a large
number of keys. Consider the following situations:

If you... Performance improves... Performance slows...

increase the number of when you retrieve data in when you enter data because
secondary keys marked as several different sorting C/SIDE has to maintain the
active sequences because the indexes for each secondary
system has already sorted key.
the data.

34 What Are Keys?

 Chapter 3. Table Fundamentals

If you... Performance improves... Performance slows...

decide to use only a few keys when you enter data because when you retrieve data. You
C/SIDE has a minimal may have to define or
number of indexes to reactivate the secondary
maintain. keys to get the appropriate
sortings. Depending on the
size of the database, this can
take some time, as the
system builds the index.

The decision whether to use a few or many keys is not easy to discuss in
general. 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 used only rarely.

The overall speed of C/SIDE will depend strongly upon a number of factors:

· The size of your database

· The number of active keys
· The complexity of the keys
· The number of records in your tables
· The speed of your hardware, that is, the speed of your computer and its disk
system

How are the Keys Stored?

As illustrated in the figure on page 24, keys are stored in the Table Description,
which contains a list of keys. The next figure illustrates a part of the key list for
a Cust. Ledger Entry table.

What Are Keys? 35

 Chapter 3. Table Fundamentals

1 (Entry No.) Primary key

3 (Customer No.) 4 (Date) Secondary Key

Key Description
5 (Document Type) 6 (Document No.) 3 (Customer No.) Secondary Key

3 (Customer No.) 36 (Open) 43 (Positive) 37 (Due Date) Secondary Key

The figure illustrates the first four keys of this table–the primary key and three
secondary keys. The primary key consists of a single field ID. The first
secondary key contains two field IDs, while the second and third secondary
keys contain three and four fields respectively.

36 What Are Keys?

 Chapter 3. Table Fundamentals

3.3 Saving, Viewing, and Sorting Data

When you have designed the fields and keys for a new table, you have to save
the table in your database before you can use it. Once you have saved a table,
it will appear in the list of tables shown in the Object Designer.

To save a table in the database:

1 Make sure that focus is on the Table Designer.

2 From the File menu, choose Save. C/SIDE will display the following:

3 Enter a number to serve as a unique identification of the table in the ID field.

Notice that there are restrictions about which numbers you can use. Please
contact your NTR for information.

Normally you use a form to view the data in a table, but you can also view the
data in a table directly by running the table from the Object Designer.

To view the data in a table without using a form:

1 Choose Object Designer from the Tools menu.

Saving, Viewing, and Sorting Data 37

Chapter 3. Table Fundamentals

2 In the Object Designer, select the table you want to view and click the Run
button. C/SIDE will display the data in a tabular format:

The order in which the information appears in the window above reflects the
sorting order defined by the current key. If more than one key is defined for the
table, you can switch between the sorting orders these keys define.

To view the table data in different sorting orders:

1 Run the table from the Object Designer. C/SIDE will display the following:

2 From the View menu, choose Sort. C/SIDE will display:

38 Saving, Viewing, and Sorting Data

 Chapter 3. Table Fundamentals

Select the key here

Select ascending or
descending order
here

3 Select the key that defines the sorting order you want, and choose whether
you want the records displayed in ascending or descending order. Click the
OK or the Apply button to apply the new key. If you choose OK, the Sort
dialog closes; if you choose Apply, the Sort dialog stays open. Using Apply
is convenient if you frequently change the sorting order.

Normally data is entered in a table by using a form, but it is also possible to

enter it directly in a table.

To add records to a table without using a form:

1 Choose Object Designer from the Tools menu.

2 In the Object Designer, select the table you want to add records to and click
the Run button. C/SIDE will display the table in a tabular format:

3 Place the cursor in a blank line. Enter data in the fields and press Enter. You
can use Tab, Shift-Tab and the arrow keys on the keyboard to navigate
between the fields.

Saving, Viewing, and Sorting Data 39

Chapter 3. Table Fundamentals

4 When you have finished entering data, close the table. (You do not have to
save it, as the records are saved and updated whenever you leave a field
after entering a value in it.)

40 Saving, Viewing, and Sorting Data

 Chapter 3. Table Fundamentals

3.4 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 “sub-database,”
and its primary use is to separate and group data in the same database. As
mentioned on page 27, fields and tables are identified by a number.
Companies are identified not by a number but by a name. A company
“bundles” one or more data tables together into a logical superstructure that
is identified by a 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. How to do this is described in the Installation and System Setup
manual.

Consider a database with four tables as shown in this figure:

Table Description Company A Company B Company C

G/L Account Data Data Data

Customer Data Data Data

Vendor Data Data Data

Report Menu Option Common Data

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, all 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. As 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.

The idea of a company can be explained by an analogy with records in C/AL:

When you work with records in C/AL, you can use a WITH statement in order to
tell the system that whenever you refer to a field, you mean that field within a
specific record. That is, within the scope of the WITH statement, you do not
explicitly need to refer to <record>.<field> but just to <field>, as <record> is
assumed as the default. Likewise, by opening a company you specify a default
group of tables to which all your database accesses will be directed.

Dividing the Database into Companies 41

Chapter 3. Table Fundamentals

Even though you have selected a specific company, you can still access data in
any table in any other company. To do so, you must use the C/AL function
<Record>.CHANGECOMPANY to explicitly define which other company you
want to access.

More than one application can access the same company and the same
table(s) at the same time. How the DBMS controls these multiple accesses is
described in the section What is Table Locking? on page 350.

42 Dividing the Database into Companies

 Chapter 3. Table Fundamentals

3.5 Special Table Fields

In addition to the conventional data fields, which simply hold values, two kinds
of specialized fields are available for data retrieval:

· FlowFields
· FlowFilter fields

What Are FlowFields?

FlowFields are a powerful feature of the C/SIDE database system. The
FlowField is a fundamental concept that strongly influences the way a C/SIDE
application is designed.

FlowFields and the underlying concept of SumIndexFields have been designed

in order to increase the performance in such activities as calculating the
balance of your customers, which in traditional database systems involves a
series of accesses and calculations before a result is available. Why such a
result will be immediately available when you use FlowFields will be clear as
you read through the rest of this section and Appendix C on page 339, which
deals with the underlying concept of SumIndexFields.

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. Actually
the information in the FlowFields exists only at run time. The values in
FlowFields are automatically initialized to 0 (zero). To update a FlowField, you
must use the C/AL function <Record>.CALCFIELDS. Notice that 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.

There are seven types of FlowFields:

FlowField Field Type Description

Type
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

Special Table Fields 43

 Chapter 3. Table Fundamentals

FlowField Field Type Description

Type
Lookup any Looks up a value in a column in another table
Example

Consider the Customer table in the figure below. 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.

Customer (Table data)

Customer Name Country Code Balance Any Entries

(FlowField) (FlowField)
10000 Windy City Solutions US 60 Yes

10010 Modern Cars Inc. US 90 Yes

10020 Jean Saint Laurent FR 210 Yes

10030 Russel Publishing 0 No
UK
10040 La Cuisine Française FR 300 Yes

Virtual part of
Customer Entry (Table data) the table data

Customer Date Comment Amount

10000 10

10000 20

10000 30

10010 40

10010 50

10020 60

10020 70

10020 80

10040 90

10040 100

10040 110

44 Special Table Fields

Chapter 3. Table Fundamentals

The figure shows that the value in the FlowField Balance 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, that is

Sum = 10 + 20 + 30 = 60.

The values shown in the Balance column in the Customer table for customers number 10010, 10020,
10040 are found in the same way. Customer number 10030 has the value 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. Sums in FlowFields are always based on a calculation formula. The
calculation formula for the Balance field is

Sum(“Customer Entries”.Amount WHERE(CustNo=FIELD(CustNo)))

Correspondingly, the Any Entries field, which indicates whether any entries exist, has the following
definition:

Exist(“Customer Entries” WHERE(CustNo=FIELD(CustNo)))

To create a FlowField:

1 Design the table in the Table Designer. C/SIDE will typically display:

2 Click on the line defining the field that you want to turn into a FlowField.

3 From the View menu choose Properties. C/SIDE will display the property
sheet:

Special Table Fields 45

 Chapter 3. Table Fundamentals

4 Change the value of the FieldClass property from Normal to FlowField

5 Now you have to enter a calculation formula for the FlowField. This is done
with the CalcFormula property. The next section tells you how.

Calculation Formulas and the CalcFormula Property

A FlowField is always associated with a calculation formula that determines
how the value in the FlowField is calculated. Below is a description of the valid
syntax for the CalcFormula property:

<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>)))

where...

46 Special Table Fields

 Chapter 3. Table Fundamentals

Symbol Explanation
<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 (FlowFilter fields are
discussed in the next section). Notice that it is a requirement that a key for the
other table exists and includes 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.
To create, view, or edit a calculation formula:

1 Click the field for which you want to create, view, or edit the calculation
formula.

2 From the View menu, choose Properties. Find the CalcFormula property in
the property sheet:

Enter the
calculation formula
here

3 You can either enter the calculation formula directly or click the assist-edit
button. When you click the assist-edit button, C/SIDE will display:

Special Table Fields 47

 Chapter 3. Table Fundamentals

4 Click the drop-down button to select the appropriate calculation method.

Click the Reverse Sign option if you want 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 you want to get the information. If necessary, you
can add a table filter to specify a limited set of records. Click the assist-edit
button to the right of the Filter field. C/SIDE will display the Table Filter
window:

Each line defines a

field filter. Notice
that there are
implicit logical
ANDs between the
lines.

5 At each line in this window, you can define a field filter. For each field filter
you must specify a field, a type, and a value and you can set the
OnlyMaxLimit and the ValueIsFilter options. The following example below
illustrates where the information in this window come from.

Example

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.

48 Special Table Fields

 Chapter 3. Table Fundamentals

The Amount field that

contains the
information to be
summed. This field is
defined as a
SumIndexField in the
key for the G/L Entry
Table.

The Field column in the

Table Filter window
contains references to
fields (columns) in the The Value column in
G/L Entry table. the Table Filter
window contains
references to fields
(columns) in the G/L
Account table.

The Balance at Date

FlowField
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 will be able to enter filter values in a FlowFilter form:

Special Table Fields 49

 Chapter 3. Table Fundamentals

This means that if the user enters a date filter expression in the Date Filter field, it will be 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 bound 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 will transform 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 a specific
value.

Using FlowFilter Fields in the Calculation Formula

End users may want to limit calculations so that they include only those values
in a column that have some specific properties. For example the user may want
to sum up 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.
.

50 Special Table Fields

Chapter 3. Table Fundamentals

Table B

Table A Constants

Ordinary fields

Table C
Calculation
FlowFilter fields
Formula

FlowFields

Table D

Path for information used in the calculation formula

Path for data used in computation of FlowFields

The above figure illustrates the relations between various types of database
fields and the calculation formula. The filters defined in the calculation formula
can consist of constants, of values from ordinary fields and of filters given as
parameters in FlowFilter fields. FlowFilter fields are fields in which the end user
can enter input a filter (via the user interface in a C/SIDE application) that will
affect the calculation of a FlowField.

Special Table Fields 51

Chapter 3. Table Fundamentals

52 Special Table Fields

Chapter 4
Customizing and Maintaining
Tables

As you create tables, you’ll want to take

advantage of properties and triggers. By setting
properties for your tables, you can set up defaults
to use throughout your database, and by defining
C/AL code in triggers, you can modify the
system’s default behavior.

This chapter shows you how to use properties and

triggers when you design tables. Furthermore, it
shows how to create relationships between
tables. Finally, the chapter explains how to deal
with the problems you may encounter when you
change tables that contain data.

· Viewing and Modifying Properties

· Using Table and Field Triggers
· Setting Relationships Between Tables
· Changing Tables That Contain Data
 Chapter 4. Customizing and Maintaining Tables

4.1 Viewing and Modifying Properties

This section describes how you can use properties in your table design. As you
have learned in the previous section the properties in a C/SIDE table can be
divided into these categories

· Table Properties
· Field Properties
· Key Properties

Viewing and Modifying Table Properties

A table in C/SIDE has a number of properties that describe the behavior of the
table in your environment. When you create a table, C/SIDE automatically
defines a number of default values for these properties. Depending on the
purpose of the table 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 this property to...

ID define the ID of the table.
Name define a name (used as caption) for the table.
Description 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 determine whether the system will create a version of the data for
each company in the database.
IncludeDataInDesc determine whether data will be included when application objects
are exported and imported.
RemoteServerNo redirect database requests when the server multiplexer C/PLEX is
used.
Permissions define extended permissions for the table.
LookupFormID define the ID of the form you want to use as a lookup.
DrillDownFormID define the ID of the form you want to use as a drill down.
DataCaptionFields define a list of fields to be used as captions when a record from this
table is displayed in, for example, a form.
Refer to the online Reference Guide for additional information about the above
properties.

52 Viewing and Modifying Properties

 Chapter 4. Customizing and Maintaining Tables

To view or modify table properties:

1 From the Tools menu, choose Object Designer.

2 Click the Table button in the Object Designer window to get a list of the
tables.

3 Select a table and click the Design button. C/SIDE will display the table in
the Table Designer:

The Table
Designer

4 Place the cursor on an empty line in the Table Designer. (If you place the
cursor on a line defining one of the fields in the table, you will get the
properties for the field instead of those for the table.)

5 Choose Properties from the View menu. C/SIDE will display the Property
Sheet:

The Property
Sheet displays the
properties for the
current table.

6 If you want to modify the setting of a property, simply enter the new value
on the Property Sheet. When you have entered the new value, update the

Viewing and Modifying Properties 53

 Chapter 4. Customizing and Maintaining Tables

property by either pressing Enter or simply moving the cursor away from the
field.

7 To get Help for a property, point at it on the Property Sheet and press F1.

Example

LookUpFormID is a typical example of a property you will want to modify. The default value for the
LookUpFormID property is <Undefined>. By changing this value, you can determine which form the
system will display when F6 (Lookup) is pressed.

Viewing and Modifying Field Properties

Just like tables, all fields in C/SIDE have a number of properties that describe
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:

Property Name Use this property to...

Name specify the name of the field.
Caption specify the text the system displays next to a control that is based on
the field.
Description include an optional description of the field. This description is for
internal purposes only and is not visible to the end user.
Enabled determine whether the field is enabled.
InitValue define an initial value for a field.
FieldClass define the class for a field (that is, specify whether it is a normal
field, a FlowField or a FlowFilter field).
CalcFormula define a formula used by a FlowField.
AltSearchField define an alternative search field.
DecimalPlaces set the number of decimal places shown to the user. This property
also performs validation of whether user input conforms to this
setting.
Editable determine whether a field can be edited.
NotBlank force the user to make a non-blank entry in this field.
Numeric force the user to enter numbers in this field.
CharAllowed set the characters you will allow the user to enter in this field.
DateFormula validate the syntax of a date expression entered by the user.
MinValue set the minimum value for the contents of a field.
MaxValue set the maximum value for the contents of a field.

54 Viewing and Modifying Properties

Chapter 4. Customizing and Maintaining Tables

Property Name Use this property to...

Title add a title to a field. The first letter in each word is capitalized.
ValuesAllowed specify 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.
TableRelation define relationships to other tables. Refer to the section Setting
Relationships Between Tables on page 61 for a detailed discussion
about how to create table relations.
ValidateTableRelation tell the system whether or not it should validate a table relationship.
TestTableRelation tell the system whether or not you want it to include this field when it
tests the table relationships
BlankZero define that the field will be shown as blank if the value is 0 (zero) or
FALSE.
DataLength define the length of a data field.
BLOBType define the subtype of a BLOB field (for example a Bitmap or Memo).
OptionString define an option string (a comma-separated string of options). The
maximum size is 1000 characters.
ClosingDates determine whether closing dates are allowed.

Refer to the online C/SIDE Reference Guide for additional information about
the above properties.

To view or modify field properties:

1 From the Tools menu, choose Object Designer.

2 Click the Table button in the Object Designer window to get a list of the
tables.

3 Select a table and click the Design button. C/SIDE will display the table in
the Table Designer:

Viewing and Modifying Properties 55

 Chapter 4. Customizing and Maintaining Tables

The Table Designer

Place the cursor at

the line defining the
field for which you
want to change or
view the properties.

4 Place the cursor on the line in the Table Designer that defines the field for
which you want to access the properties.

5 From the View menu, choose Properties. C/SIDE will display the Property
Sheet:

The Property Sheet

displays the
properties
associated with the
current field.

6 If you want to modify the setting of a property, simply enter the new value
on the Property Sheet. When you have entered the new value, update the
property by either pressing Enter or simply moving the cursor away from the
field.

7 To get Help for a property, point at it on the Property Sheet and press F1.

Example

The DecimalPlaces property is a typical example of a field property you may want to change. When
you create a new field of the type decimal, C/SIDE will assume that you want the value to be
formatted as a currency. If your decimal field will not contain a currency, you can use this property to
determine the number of decimal places that will appear on the screen.

56 Viewing and Modifying Properties

 Chapter 4. Customizing and Maintaining Tables

Viewing and Modifying 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 this property to...

Enabled determine whether the system will maintain an index for the key. You
cannot use a key unless it is enabled.
Key define the key.
SumIndexFields determine the fields for which the system will maintain a
SumIndex.
KeyGroups determine which keygroups the key is a member of.
BackupKey see whether any errors occurred the last time you restored a backup.

Refer to the online C/AL Reference Guide for additional information about the
above properties.

To view or modify properties for the keys of a particular table:

1 From the Tools menu, choose Object Designer.

2 Click the Table button in the Object Designer to get a list of the tables.

3 Select a table and click the Design button. C/SIDE will display the table in
the Table Designer:

The Table Designer

Viewing and Modifying Properties 57

 Chapter 4. Customizing and Maintaining Tables

4 From the View menu, choose Keys. C/SIDE will display:

5 Place the cursor on the line defining the key for which you want to view or
modify the properties.

6 From the View menu, choose Properties. C/SIDE will display the Property
Sheet:

The Property
Sheet for a key

7 If you want to modify the setting of a property, simply enter the new value in
the Property Sheet. When you have entered the new value, update the
property by either pressing Enter or simply moving the cursor away from the
field.

8 To get Help for a property, point at it on the Property Sheet and press F1.

58 Viewing and Modifying Properties

 Chapter 4. Customizing and Maintaining Tables

4.2 Using Table and Field Triggers

C/SIDE recognizes certain things that happen to a table when you use it, for
example that you insert or modify data. In response, you can get the system to
execute C/AL code defined in a trigger. Triggers can be thought of as
predefined functions that are executed when certain things happen. The
bodies of these functions are initially empty and must be defined by the
developer. By defining C/AL code in triggers, you can change the default
behavior of the system. The triggers in a C/SIDE table can be divided into two
categories:

· Table triggers
· Field triggers
Tables in C/SIDE have the following triggers:

Table Trigger Name Executed when...

OnInsert a new record is inserted into the table.
OnModify a record in the table is modified.
OnDelete a record in the table is deleted.
OnRename a record is modified in a field that is part of the primary key.
Fields in tables have these triggers:

Field Trigger Name Executed when...

OnValidate data is entered in a field or when <Record>.VALIDATE is executed in
C/AL code.
OnLookup Lookup (F6) is activated.
If you are not familiar with C/AL programming please refer to chapter 13,
Introducing the C/AL Language, on page 249.

To define or modify a trigger for a table or a field:

1 Click the Table button in the Object Designer window to get a list of the
tables.

2 Select the table and click the Design button. The system will open the Table
Designer, containing a list of the fields in the table.

3 Choose View, C/AL Code (F9). C/SIDE will display the code for the table in
the Table Designer. The system uses the position of the cursor in the Table
Designer to determine what code to display. That is, if you place the cursor

Using Table and Field Triggers 59

Chapter 4. Customizing and Maintaining Tables

on a specific field in the Table Designer, the code in the C/AL Editor is
automatically scrolled so that the first trigger related to that field appears at
the top of the window. If the cursor is placed on an empty line in the Table
Designer, the system shows the first trigger related to the table itself.
Notice, however, that the position of the cursor in the Table Designer does
not restrict your access to other triggers. You can always scroll up and down
through the triggers in the C/AL editor.

4 Enter or modify the C/AL code in the relevant trigger(s).

60 Using Table and Field Triggers

 Chapter 4. Customizing and Maintaining Tables

4.3 Setting Relationships Between Tables

As mentioned in the section Introduction to C/SIDE Application Design on page
14, it is common to distinguish among three types of relationships between
tables in relational database design:

· One-to-Many Relationships
· Many-to-Many Relationships
· One-to-One Relationships
Because the one-to-many relationship is the most commonly used, this section
will focus on this type of relationship. If your database design model indicates
that you need to set up a many-to-many relationship, you probably have a
problem in your design–it may be inefficient. You normally break down a
many-to-many relationship into two one-to-many relationships. A one-to-one
relationship is usually undesirable and can often be avoided by simply
combining the two tables. To learn more about database design, refer to one of
the text books mentioned in the subsection Recommended Books on Database
Design on page 19.

Why Use Relationships?

If your database contains tables with related data 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 in other tables.
· automatically propagate changes from one table to other tables.

Table Relations and the TableRelation Property

Table relations are defined using the TableRelation property. This property is
very flexible and allows you to define both simple and advanced table
relations. A typical simple table relation consists of just a table ID and an
optional field ID, while advanced table relations are typically prefixed with a
conditional statement and include filters. The syntax for table relations is:

Setting Relationships Between Tables 61

 Chapter 4. Customizing and Maintaining Tables

<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>)

where...

Symbol Explanation
<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 table filter can be either a constant expression or a filter expression.
<DstFieldNo> Specifies the destination field number.
<Filter> A filter expression such as 10|20..30.

Creating Basic Table Relations

When you create table relations you can either enter them manually or use the
assist edit tool. You will usually enter basic table relations such as

<TableNo>[.<FieldNo>]

directly on the Property Sheet, whereas you will use assist-edit to enter the
more advanced table relations that use conditions and filters. Below you will
see how to create (basic) table relations by entering them directly on the
Property Sheet. In the following section, you will see how to use the assist edit
tool to do the same.

To create a basic table relation:

1 From the Tools menu, choose Object Designer.

62 Setting Relationships Between Tables

 Chapter 4. Customizing and Maintaining Tables

2 Click the Table button in the Object Designer window to get a list of the
tables.

3 Select a table for which you want to create a relationship, and click the
Design button. C/SIDE will display the table in the Table Designer.

4 Make sure that the cursor is placed in the field for which you want to set up
a relation. Select Properties from the View menu. C/SIDE will display the
Property Sheet for the field:

Define the table

relation here

5 Enter the table relation directly in the value field for the TableRelation
property. Simple table relations use the syntax: <TableNo>.[<FieldNo>].
Refer to the next section to learn how to use the assist-edit tool to create
advanced table relations.

Example

Assume that you have an Orders table that stores orders and a Sales Person table that stores the
names of all sales person in your company. In the Orders table, you can include a field called Sales
Person that identifies the sales person. By setting up a relationship between these two tables you
can get the system to check whether the sales person field in the Orders table contains a valid code.

Setting Relationships Between Tables 63

 Chapter 4. Customizing and Maintaining Tables

The Orders table When data is entered in a

Sales
Person field in the Sales Person
column in the Orders table,
the system uses the
relation to the Sales
Person table to check
whether the code is valid.

The TableRelation property

The Sales for the Sales Person
Code
Person table column is set to “Sales
Person”.Code.

Example

Assume that you have a Vendors table of all your vendors and a Currency Code table. Then you can
create a relationship between a Currency Code field in the Vendors table and the Currency Code
table. This will allow users to lookup (F6) information about valid currency codes.

Example

Assume that you have a Vendors table and a Currency Code table as in the example above. If you
change one of the currency codes in the Currency Code table, the system will automatically
propagate this change to all the tables that refer to this code.

Creating Table Relations with Assist-Edit

C/SIDE has an assist-edit tool to help you enter advanced table relations. By an
advanced table relation, we mean a table relation that is prefixed with a
conditional statement and uses filters.

To create a table relation using assist-edit:

1 Start exactly as if you are creating a basic table relation. Repeat steps 1 to 4
as described on page 62.

2 Click the assist-edit button to the right of the Field field for the
TableRelation property. C/SIDE will display

64 Setting Relationships Between Tables

Chapter 4. Customizing and Maintaining Tables

3 Fill in Condition fields by using the assist-edit to set the relevant table
filters. For example, you can look up in different tables, based on the value
in an option field.

4 Enter in the Table field the name of the table to which you want to make a
relation, or use the lookup button to select a table from a list. In the Field
field, you can enter the name of the field or use the lookup button to select
from a list of fields (those in the table you have entered in the Table field).

5 If necessary, define a table filter (for the table in the Table field) in the Table
Filter field.

Setting Relationships Between Tables 65

 Chapter 4. Customizing and Maintaining Tables

4.4 Changing Tables That Contain Data

When you design the tables in your database, you determine which fields they
contain. Sometime later, you may want to modify the design of some of the
tables in your application. Typically you will want to add or delete fields, or
make changes to field names or data types.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C/SIDE is designed to ensure that you never lose data when you modify the
design of a table that contains data.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Rules for Changing Tables

Whether it is possible to make changes to a table depends on a number of
things. If you haven’t added data to the table, you can modify it as you like, but
when the table contains data, a number of restrictions apply. The table below
gives some general rules:

Modification Rules

Changing a field name You can always change the name of a field.

Changing a 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.

Adding a field to a table You can always add a field to a table.

Deleting a field In order to delete a field, you must delete all data from the field
in all records in the table. Furthermore you must remove all
references to the field from other tables, forms and reports

Changing the length of a You can always increase the length of a String field. Whether
String field 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.

66 Changing Tables That Contain Data

Chapter 5
Special C/SIDE Tables

In addition to the normal database tables, C/SIDE

has three other types of tables that serve special
purposes in C/SIDE applications. These are called
temporary, system and virtual tables. Temporary
tables are used as a repository for temporary
information at run time, while the two other types
are system generated tables that provide various
information about the current state of the system.

This chapter introduces you to the special C/SIDE

tables and explains how to use them in your
design.

· What Is a Temporary Table?

· What Is a System Table?
· What Is a Virtual Table?
· Overview of C/SIDE Virtual Tables
 Chapter 5. Special C/SIDE Tables

5.1 What Is a Temporary Table?

A temporary table can be regarded as a temporary variable that is used to hold
a table. A temporary table is intended to be used as a buffer for table data in
your C/AL programs. If you are not familiar with C/AL, please refer to chapter
13, Introducing the C/AL Language, on page 249.

You can do almost anything with a temporary table that you can do with a
normal database table; the only differences between a normal database table
and a temporary table are that:

· Temporary tables aren’t stored in the database but only held in memory on
your workstation until the table is closed.
· Temporary tables can’t have more than one key
· The write transaction principle that applies to normal database tables does
not apply to temporary tables. If you are not familiar with the transaction
principle, please refer to the section Write Transactions and Recovery on
page 344

The temporary C/SIDE C/SIDE

C/SIDE
tables are Client Client Client
...
stored only on
the client.

C/SIDE
Server

The advantage of using a temporary table is that all interaction with a

temporary table takes place on the client. This reduces the load both on the
network and on the server.

When you need to perform many operations on data in a specific table in the
database, you can load the information into a temporary table while you
modify it. Because all operations are local, this will speed up the process.

68 What Is a Temporary Table?

 Chapter 5. Special C/SIDE Tables

Defining and Using a Temporary Table

Before you can use a temporary table in your C/AL code, you have to define it.
The variable holding a temporary table is defined just like any other global or
local variable.

To define a temporary table:

1 We assume that you are working in the C/AL editor. From the View menu,
choose 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, C/SIDE will display:

2 Enter a name for the temporary table variable and enter Record as data
type. Use the lookup button in the Subtype field to select the table you want
to make a temporary copy of.

3 With the cursor still on the line that defines the temporary table, choose
Properties from the View menu to display the Property Sheet. C/SIDE will
display:

4 Change the Temporary property value to Yes.

What Is a Temporary Table? 69

Chapter 5. Special C/SIDE Tables

After you have created a temporary table as described above, you can use it in
your C/AL code. You can apply filters and perform searches just the way you do
when you work with normal database tables.

70 What Is a Temporary Table?

 Chapter 5. Special C/SIDE Tables

5.2 What Is a System Table?

System tables are stored in the database just like normal database tables. The
only difference between system tables and normal ones is that system tables
are created automatically by the system. The information in system tables is
closely related to the DBMS, which uses the system tables to manage, for
example, users’ IDs and permissions in C/SIDE.

It is possible to read, write, modify and delete the information in system tables.

C/SIDE C/SIDE C/SIDE

Client Client Client
...

System tables are

stored in the
database like C/SIDE
normal database Server
tables.

There are six system tables in C/SIDE:

· User Table
· Member Of Table
· User Group Table
· Permission Table
· Company Table
· Database Key Groups Table
The first four tables in the list above all deal with user permissions.

About permissions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
In order to insert, modify or delete information in the User, Member Of, Group,
and Permission tables, you must have at least the same permissions as the
users you want to modify. This means that you can’t assign to other users or
take away from them permissions that you don’t have yourself.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What Is a System Table? 71

 Chapter 5. Special C/SIDE Tables

The following subsections provides an overview of these system tables. The

User, Member Of, User Group, and the Permission table are also described in
the book called Installation and System Setup.

The User System Table

The User system table provides an overview of all the user IDs you have
defined in your database. Each record in the User system table defines a single
user ID.

For each ID defined in your database, the User system table includes
information about the password (displayed encrypted on your screen), the real
name of the user and for how long this ID will be valid. You can create new user
IDs by entering appropriate data in this table; correspondingly, you can
remove a user ID by deleting the record from this table. (Of course this depend
on your own permissions.)

Deleting a record
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If you delete a record in the User system table, the system will automatically
remove the corresponding entries in the Member Of system table.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The Member Of System Table

The Member Of system table provides an overview of which user groups a user
is member of. Each user (ID) can be a member of any number of user groups.

72 What Is a System Table?

 Chapter 5. Special C/SIDE Tables

The User Group System Table

The User Group system table provides an overview of the user groups in your
database. A user group specifies a set of permissions. The exact permissions
for each user group are defined in the Permissions system table.

Deleting a Record
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If you delete a record in the User Group system table, the system will
automatically delete the corresponding entries in the Member Of and
Permission system tables.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What Is a System Table? 73

 Chapter 5. Special C/SIDE Tables

The Permission System Table

You can use the Permission system table to define what different user groups
are allowed to do. Permissions are specified for objects; you can specify the
exact set of permission per table, form, and so on. You can specify that a user
group has no (blank field), Full (Yes), or Indirect permissions to perform the
following actions:

· Read
· Create/Insert
· Modify
· Delete
· Execute

The Company System Table

The Company system table provides 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 in your database by deleting the corresponding record in the
Company table. (When you do that, you delete all the tables in the company. At
the same time you also delete all permissions that include this company.)

74 What Is a System Table?

 Chapter 5. Special C/SIDE Tables

The Database Key Groups System Table

The Database Key Groups system table provides an overview of the key groups
defined in your database. Each record in this table shows a key group.

Note about Key Groups

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 make use of key groups, select File, Database, Information and then
press the Table button; select the Key Groups option button on the Database
Information window that opens.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What Is a System Table? 75

 Chapter 5. Special C/SIDE Tables

5.3 What Is a Virtual Table?

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 the
system at run time.

When to Use 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 working with ordinary tables. For example you can use filters to get
subsets or ranges of integers or dates.

The virtual tables provide information such as:

· integers in the range -1.000.000.000 to 1.000.000.000.

· dates within a given period.
· an overview of operating system files.
· an overview of logical disk drives.
· a trace of database requests from your client to the database.
· an overview of connected users.
· an overview of the operating system files that store the database.

76 What Is a Virtual Table?

 Chapter 5. Special C/SIDE Tables

5.4 Overview of C/SIDE Virtual Tables

C/SIDE contains eight types of virtual tables, divided into two categories:

Category Includes...
Simple Date, Integer, File, Drive
Advanced Monitor, Session, Database File, Table Info
The simple virtual tables contain lists of simple information, while the
advanced virtual tables contain information that is more complex.

Using the Simple Virtual Tables

The virtual tables in this category provide you with easy access to dates,
integers, information about your operating system files and the logical drives
on your computer.

The Date Virtual Table

This virtual table provides easy access to days, weeks, months, quarters, and
years. The Date virtual table has the following fields

Field Name 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
The figure below illustrates how you should think of the Date virtual table. For
each period type, there are many records in the Date table.

The period type can be

days, weeks, months,
quarters, or years.

Overview of C/SIDE Virtual Tables 77

 Chapter 5. Special C/SIDE Tables

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.

Example

The Date virtual table is most frequently used to provide a range of dates, the G/L Balance form
below is a typical example. You will learn how to design forms in part 3, Forms, on page 87.

This information is
provided by the
Date virtual table

The Integer Virtual Table

This virtual table includes integers in the range -1.000.000.000 to
1.000.000.000. The Integer virtual table has only one field:

Field Name Description

Integer An integer in the range -1.000.000.000 to 1.000.000.000
By applying a filter to this virtual table, you can easily get a subset or range of
numbers that can be used to control looping in reports.

The File Virtual Table

This virtual table provides an overview of the files in a directory on your disk
system. The File virtual table has the following fields

Field Name Description

Path The filter on this field determines which directory will be shown.
Is a File The value Yes indicates that the entry is a file, while the value No
indicates that the entry is a directory.
Name The name of the file or directory.

78 Overview of C/SIDE Virtual Tables

 Chapter 5. Special C/SIDE Tables

Field Name Description

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.

The Drive Virtual Table

This virtual table provides an overview of the logical drives on your computer.
The Drive virtual table has the following fields:

Field Name Description

Drive The name of the drive, such as A: or D:
Removable Indicates whether the disk is removable (a floppy disk) or a fixed disk
Size (KB) The total size of the disk
Free (KB) The amount of free space on the disk
Notice that....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
if there is no diskette in your disk drive, Size (KB) and Free (KB) will be shown
as -1.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the Advanced Virtual Tables

The advanced virtual tables are most likely to be used by the system
administrator, as they provide a lot of useful information about the users that
are attached to the system. They also provide information about the current
state of the system.

The Monitor Virtual Table

This virtual table traces all database requests from the client to the tables in
your database. You can get access to the Monitor virtual table directly from
C/SIDE by choosing Client Monitor from the Tools menu.

This virtual table is used by C/AL programmers to get an overview of the time
consumption of specific operations. C/AL programmers can use the
information in this virtual table to tune their code for optimal performance. The
Monitor virtual table has the following fields:

Overview of C/SIDE Virtual Tables 79

Chapter 5. Special C/SIDE Tables

Field Name Description Possible Values

Entry No. Successive numbers From 1 to 231-1
that are increased for
each database
request
Function The type of LOCKTABLE, DELETE, MODIFY, INSERT, DELETEALL, Create
database request 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
Parameter No. The number of the Depending on the number of parameters
parameter
Parameter The name of the Table, Key, Order, Filter, Search Method, Search Result,
parameter Records Found, Sum, CPU (ms), Records Read, Sum
Intervals, Records Deleted, Disk Reads, Disk Writes,
Record, Wait, SumIndexFields, BLOB Field, Commit, User
ID, File Name
Number If the parameter is a Any numeric value
number, the value is
shown in this column
Data Any non-number Any string
parameter is shown
in this column

You can access the Monitor virtual table directly from C/SIDE’s user interface:

1 From the Tools menu, choose Client Monitor. C/SIDE will display:

80 Overview of C/SIDE Virtual Tables

 Chapter 5. Special C/SIDE Tables

Use the Start and Stop

buttons to control the
Client Monitor

2 Click the Start button to activate the Client Monitor.

3 You can now close the Client Monitor window while you perform the tasks
you want to investigate.

4 When you have completed these tasks, choose Client Monitor from the
Tools menu to display the window again.

5 Click the Stop button to stop the Client Monitor.

The Session Virtual Table

This virtual table provides an overview of the users connected to the DBMS. If
you delete a record in this virtual table, the corresponding user will be
disconnected. The Session virtual table has the following fields

Field Name Description

Connection ID The ID of the connection.
User ID The User ID for a connected user.
My Session Shows whether a session belongs to you.
User Name The user’s real name.
Login Time The time when the user logged in.
Login Date The date when the user logged in.
Cache Reads The number of cache read operations performed(A).
Disk Reads The number of disk read operations performed(A).
Disk Writes The number of disk write operations performed(A).
Records Found The number of records found since the user logged in.

Overview of C/SIDE Virtual Tables 81

 Chapter 5. Special C/SIDE Tables

Field Name Description

Records Scanned The number of records scanned through since the user logged in.
Records Inserted The number of records inserted since the user logged in.
Records Deleted The number of records deleted since the user logged in.
Records Modified The number of records modified since the user logged in.
Sum Intervals The number of jumps between value intervals made by the system
when calculating sums since the user logged in. A high value may
indicate that an inefficient key is being used.

(A) Only if Commitcache = Yes

C/SIDE uses this virtual table to display database information.

To access the Session virtual table from C/SIDE:

1 From the File menu, choose Database, Information.

2 Click the Sessions tab.

3 Click the drill-down button in the Current Sessions field. C/SIDE will display:

The Database File Virtual Table

This virtual table provides an overview of the operating system files that stores
the database. The DatabaseFile virtual table has the following fields:

Field Name Description

No The number of the operating system file
File Name The operating system file name

82 Overview of C/SIDE Virtual Tables

 Chapter 5. Special C/SIDE Tables

Field Name Description

Size (KB) The size of the operating system file in KB
Total Reads The number of read accesses since the database was opened
Mean Read Time (ms) The average time for a read operation (in msecs)
Reads In Queue (A) Number of read operations waiting in queue
Total Writes Number of write operations since the database was opened
Mean Write Time (ms) The average time for a write operation (in msecs)
Writes In Queue (A) Number of write operations waiting in queue (in msec)
Disk Load (%) A percentage weight describing the load on the disk

(A) Only if Commitcache = Yes

C/SIDE uses this virtual table to show database information.

To access the Database File virtual table from C/SIDE:

1 From the File menu, choose Database, Information.

2 Click the Database tab.

3 Click the drill-down button in the Database Name field. C/SIDE will display:

Note that the above window displays only some of the fields in the Database
File virtual table.

The Table Information Virtual Table

This virtual table contains various information about database tables. The
Table Information virtual table has the following fields:

Overview of C/SIDE Virtual Tables 83

Chapter 5. Special C/SIDE Tables

Field Name 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.
Records The number of records in the table.
Record Size A value expressing the average size of a record. Calculated as
1024*Size(KB)/Records.
Size (KB) How much space the table occupies in the database (in KB).
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 other is slack-space. Slack-space can be minimized
by optimizing the table

C/SIDE uses this virtual table to display database information.

To access the Table Information virtual table from C/SIDE:

1 From the File menu, choose Database, Information.

2 Click the Table button. C/SIDE will display:

Note that this window doesn’t display all the columns in the Table Information
virtual table. Use the horizontal scroll bar to view the information in the hidden
columns.

84 Overview of C/SIDE Virtual Tables

Part 3
Forms
Chapter 6
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 chapter introduces the fundamental concepts

and basic tasks involved in designing and using
forms.

· What Are Forms?

· Creating Forms
· Selecting, Moving and Adjusting Controls
· Saving, Compiling and Running Forms
 Chapter 6. Form Fundamentals

6.1 What Are Forms?

After you have created tables, the next step in developing a C/SIDE application
should be to design forms. In contrast to programs written in traditional
programming languages, C/SIDE applications do not execute sequentially:
they are event-driven. A major part of the logic of an application could be said
to rest with the forms: forms are used for entering information into database
tables and for retrieving and displaying information from database tables. It is
through forms that users 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 a number of 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).

The figure below shows the components of a form and how they are related.
This and the following chapters will explore each component in depth.

Form Description

Form Properties

Triggers

Controls Properties
Triggers
Forms are created and edited in the Form Designer.

What are Controls?

All information on 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 a descriptive text.

Some controls are called container controls. An example is a frame. The frame
itself does not display data or information, but it can contain a number of other
controls that you want to group. A powerful container control is the tab control.
A tab control really is a number of frames or pages that are placed on top of

90 What Are Forms?

 Chapter 6. Form Fundamentals

each other. The user can switch between the pages by clicking the tabs that
have captions. Tab controls make it possible to group information on a form so
that each page is not cluttered with information, and it is very fast and easy to
switch between pages.

Another concept is control branches, which consist of a parent control and

subordinate or child controls. The best 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 on the form.

What Are Bound and Unbound Forms and Controls?

Typically, a form is related to a database table and will be used to enter
information into the table and to display information from the table. The form
is said to be bound to the table.

An unbound form is not related to a table. An example of an unbound form is a

form that is used as a menu, from which the user can choose other forms or
reports to run.

The controls on a form that is bound to a table are usually bound to fields in
the same table. There need not be a control for every field in the table, nor do
all controls on the form need to be bound to table fields: controls that aren’t
bound to fields are called unbound controls. An example is a command button
that causes the information on the form to be printed; another is a control that
contains a descriptive text. An important category of unbound controls
includes controls displaying information–based on the underlying table or
user-entered values–that is calculated as the form is displayed.

What Are Form and Control Properties?

Properties describe how a control is placed on the form, what field it is related
to and what happens when information is entered into the field, among other
things. Different types of controls have different sets of properties. For
example, a text box, the control type that is typically used to display the
contents of a database field, has more properties than a picture box, a control
used to display bitmap pictures.

The form itself also has properties. For example, you can specify whether the
form is to be used only for displaying information or whether it will be possible
to insert new records or update existing ones.

What Are Forms? 91

 Chapter 6. Form Fundamentals

Properties are defined on the Property Sheet that can be edited when the form
is opened in the Form Designer.

What Are Triggers?

Certain predefined events that happen to a form or a control cause the system
to execute a user-definable C/AL function–the event triggers the function. The
event and the function are together called a trigger. Form triggers include
OnOpenForm, containing statements that will be executed when the form is
opened, and OnModifyRecord, containing statements that will be executed
before the system accepts changes the user makes to a record. Triggers are
edited in the C/AL editor, which can be opened from the Form Designer.

92 What Are Forms?

 Chapter 6. Form Fundamentals

6.2 Creating Forms

Forms can be created and designed manually. Although this method gives you
the highest degree of control, it may take some time to master. C/SIDE offers
an alternative method that is fast and easy to use and therefore preferable
when you are just beginning to create forms: you can use a form wizard. A form
wizard prompts you for the minimum amount of information needed to create a
form and then does the rest of the work for you. The automatically created
form can be changed later on in the Form Designer.

Forms that display one record at a time are called card forms, while forms that
show several records at a time are called tabular forms. The form wizard will
help you create either type.

A Card Form

A Tabular Form

Creating Forms 93
 Chapter 6. Form Fundamentals

Creating Forms with a Form Wizard

To create a form using the form wizard:

1 From the Tools menu, choose the Object Designer.

2 Click the Form button In the Object Designer.

3 Click the New button. C/SIDE will display this form:

4 If you are creating a form that is related to a table, type the name of the
table in the Table field. You can also click the Lookup button and choose the
table from a list. When the table name has been entered in the field, press
Enter.

5 Select the option called “Create a form using the wizard.” Then you must
select the type of form you want the wizard to create: card form or tabular
form. After this, click OK.

Creating a Card Form

To create a card form, follow the steps outlined above. Then proceed as
follows:

1 The system asks whether you want the form to have tabs or whether it
should be a plain form. A form with tabs is a multi-page form where the user
can switch between pages by clicking on the tabs.

94 Creating Forms
Chapter 6. Form Fundamentals

2 If you choose to create tabs, type a caption for each tab you want. In either
case, click the Next button when you are ready to continue.

3 In the next form the wizard displays, you must choose which fields from the
database table you want on your form. If you are creating a form with tab
controls, begin by choosing the page on which you want certain fields to
appear. You can switch between pages by clicking on the tabs, which have
the captions you have defined.

4 The form the wizard displays contains two lists: one with Available Fields
(all the fields in the table), and one with the fields that have been selected,
the Field Order list. To insert a field in the Field Order list, select it in the
Available Fields list and click the > button. You can insert all the fields at

Creating Forms 95
Chapter 6. Form Fundamentals

once by clicking the >> button. (You can remove fields from the Field Order
list by selecting them there and clicking <; you can remove them all at once
by clicking <<.)

5 The order of the fields in the Field Order list is the order in which the fields
will appear on the form. If you want a different order, move a field by
removing it from the Field Order list and inserting it again in the position you
want.

6 By clicking the Separator button, you can insert a small amount of extra
vertical space between the controls; this allows you to group information
together in a logical and visually pleasing way. (Note that tabs provide a
more powerful way of grouping information together on a form.) The
separator will be inserted after the field that is currently selected on the
Field Order list; you can remove a separator by selecting it and clicking the
< button.

7 To insert a column break, click the Column Break button. The rules for
insertion and deletion are the same as for a Separator. If you feel you need
to create three or more columns, you should consider using tabs instead.

8 When you are satisfied, click the Finish button. The form wizard will create
your form, and the Form Designer window will open containing the new
form. You can test-run the form by choosing Run from the File menu.

9 Close this window and answer Yes to save the form. You will be prompted to
enter an ID number and Name for the new form, and you can choose
whether or not the form will be compiled now. (You can also do it later, by
selecting the form in the Object Designer window and choosing Compile
from the Tools menu.)

10 When the form has been saved and compiled, it can be run. Select the form
from the Object Designer window and click the Run button.

96 Creating Forms
 Chapter 6. Form Fundamentals

Creating a Tabular Form

To create a tabular form, follow the general steps outlined in Creating Forms
with a Form Wizard on page 94. Then proceed as follows:

1 You are prompted to choose the fields from the database table that you
want on your form. The form the wizard displays contains two lists: one with
Available Fields (all the fields in the table), and one with the fields that have
been selected, the Field Order list. To insert a field in the Field Order list,
select it in the Available Fields list and click the > button. You can insert all
the fields at once by clicking the >> button. (You can remove fields from the
Field Order list by selecting them there and clicking <; you can remove them
all at once by clicking <<.)

2 The order of the fields in the Field Order list is the order in which the fields
will appear on the form. If you want a different order, move a field by
removing it from the Field Order list and inserting it again in the position you
want.

3 When you are satisfied, click the Finish button. The form wizard will create
your form, and the Form Designer window will open containing the new
form. You can test-run the form by choosing Run from the File menu.

4 Close this window and answer Yes to save the form. You will be prompted to
enter an ID number and Name for the new form, and you can choose
whether or not the form will be compiled now. (You can also do it later, by
selecting the form in the Object Designer window and choosing Compile
from the Tools menu.)

Creating Forms 97
 Chapter 6. Form Fundamentals

5 When the form has been saved and compiled, it can be run. Select the form
from the Object Designer window and click the Run button.

Creating Forms Without a Wizard

To create a form without using a wizard:

1 From the Tools menu, choose the Object Designer.

2 Click the Form button in the Object Designer.

3 Click the New button. C/SIDE will display this form:

4 If you are creating a form that is related to a table, type the name of the
table in the Table field. You can also click the Lookup button and choose the
table from a list.

5 Select Create a blank form, and click OK.

6 The Form Designer will open, displaying an empty form. Chapter 7,

Designing Forms, describes in detail how to design the form by adding
controls, changing properties and so forth.

98 Creating Forms
Chapter 6. Form Fundamentals

7 You can test-run the form at any point by choosing Run from the File menu.

8 When you have finished designing the form, close the Form Designer
window, and answer Yes to save the form. You will be prompted to enter an
ID number and Name for the new form, and you can choose whether or not
the form will be compiled now. (You can also do it later, by selecting the
form in the Object Designer window and choosing Compile from the Tools
menu.)

Creating Forms 99
 Chapter 6. Form Fundamentals

6.3 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
To move or adjust a control, you must first select it. As 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 pointing at it and clicking the mouse. In order to make it
easier to see what the mouse cursor is pointing at, the appearance of the
cursor changes as it is moved around the design area. The default appearance
is a cross, which means that the cursor is not currently pointing at any control.
As soon as the cursor points at a control, it changes into a selection cursor.
Clicking the mouse selects the control, which will be 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, in order to align all the controls in the selection
(how to actually align the controls will be described below).

100 Selecting, Moving and Adjusting Controls

 Chapter 6. Form Fundamentals

Adding to a Selection
When one control has been selected, you can add other controls to the
selection by holding down the Ctrl key when clicking to select them. As you
add controls, a box will appear around the complete selection and each control
in the selection will be marked by a circle in the upper left corner of its own
bounding box.

Marquee Selection
Another way to make a multiple selection is by marquee selection. When the
mouse cursor is in the design area but not pointing at anything (appears as a
cross), press the left mouse button and hold it down. When you drag the
mouse, a rectangle will appear–a marquee. As the rectangle expands, any
control that it overlaps, completely or partly, will be selected; there will be a
circle in the upper left corner of its bounding box. Release the mouse button
when you have finished selecting controls.

Selecting, Moving and Adjusting Controls 101

 Chapter 6. Form Fundamentals

Controls can be added to the selection individually (as described above), and a
marquee selection can be added to an existing selection by holding down the
Ctrl key while you perform the marquee selection.

Notice that ...

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
there is an option that determines how marquee selection works. In the Tools
menu, choose Options. The Marquee Full Selection option can be Yes or No.
Only if the option is set to No does the marquee selection work as described
above. If it is set to Yes, a control will be selected only if the marquee overlaps
the control completely–not just partly.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Selection and Container Controls

When you select a container control, all the contained controls are selected,
even if they are not marked as such by individual bounding boxes. Beware 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

102 Selecting, Moving and Adjusting Controls

 Chapter 6. Form Fundamentals

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 on the emphasis frame (the cursor changes into a
selection cursor as it touches the frame), the child controls will be 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 will be 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 towards it. When the cursor touches the
border of the control, it will look like a hand. Press and hold down the left

Selecting, Moving and Adjusting Controls 103

 Chapter 6. Form Fundamentals

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 afterwards–you may want to align the controls more
accurately than it is convenient to do freehand with the mouse. C/SIDE
provides two methods for aligning controls easily and accurately:

1 You can turn on the option Snap to Grid in the Format menu. When you
move a control as described above you will notice that it is not moving
smoothly, but rather 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.

Hint: the distance between the grid points are properties (HorzGrid and
VertGrid) of the form. The unit is 1/100 millimeters.

2 To align several controls, select the controls as a multiple selection and

choose the option Align from the Format menu. From the submenu that
follows you can choose from 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. Choose Left or Right to do this. Correspondingly, a
row of controls can be aligned to Top or Bottom. Beware–if you
inadvertently choose to align a columnar group to Top, for example, the
system will indeed do just this, placing all the controls on top of each other.

Sizing and Resizing Controls

When the 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
will want to change the size of a control are if you change the font size, or if you
don’t want to display all the information from a very large table field, but only
the first part. You can only resize one control at a time.

104 Selecting, Moving and Adjusting Controls

 Chapter 6. Form Fundamentals

To resize a control:

1 Select the control. It will be surrounded by a bounding box with sizing

handles.

2 Place the mouse cursor on a sizing handle. The cursor will change into a
sizing cursor.

3 Press the left mouse button and drag the control to the size you want. If
Snap to Grid is on, the sizing takes place in fixed increments, in a way
similar to the one described above for moving a control.

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 contained child of the
container.

Beware that it is quite possible to reduce the size of the containing control so
that a contained control seems to be outside the container. However, it is still
considered part of the container. As no part of it is inside the control, however,
it cannot be selected. The remedy for this is to enlarge the container so all
contained controls are inside it.

Selecting, Moving and Adjusting Controls 105

 Chapter 6. Form Fundamentals

6.4 Saving, Compiling and Running Forms

After you have designed a form, you must save and compile it before it can be
run. Normally, you will do this when you are done designing the form.
However, you may want to save a form that is not yet finished and thus cannot
be compiled, if the form is more complex than the forms described so far and
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 the Form Designer window is closed. You can
close this window in the same ways that you can close any other window.

To save a form:

1 When you are closing a form, C/SIDE will ask whether you want the form to
be saved. If it is a new form (a form that has not been saved before) you will
have to assign an ID and a name. The ID must be unique and follow the rules
for numbering objects–your NTR will provide you with this information.

Hint: if you enter ID and Name as form properties, these values will be used,
and you will not be prompted for ID and Name when you close the form.

2 The option field Compiled is by default set to TRUE (displayed as a check

mark). If your form is not yet ready to be compiled, remove the check mark
by clicking in the field.

3 Choose OK to save the form.

You can save a form without closing it by choosing Save or Save As... from the
File menu. You can use Save As... to give a form a new name.

106 Saving, Compiling and Running Forms

 Chapter 6. Form Fundamentals

Compiling a Form
Forms, like other objects in C/SIDE, must be compiled before they can be run.
As described above, you can choose to compile a form whenever you are
saving 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, as
described in Chapter 9). You can test-compile a form during design by
choosing the Compile option from the Tools menu.

Running a Form
In a finished application, your forms will be incorporated into menus or they
will be called from other forms. However, while you are designing forms, you
will often want to run them before they have been integrated into an
application.

You can run a form from the list of forms in the Object Designer window by
selecting it and clicking the Run button. (Note that forms can also be run from
inside the Form Designer by choosing Run from the File menu.)

Saving, Compiling and Running Forms 107

Chapter 6. Form Fundamentals

108 Saving, Compiling and Running Forms

Chapter 7
Designing Forms

This chapter describes how to design forms by

adding controls and by changing the properties of
forms and controls.

· Form and Control Properties

· Types of Controls
· Adding Controls
· Tools for Customizing Controls
· Setting Control Properties
· How to Use Controls in Applications
 Chapter 7. Designing Forms

7.1 Form and Control Properties

As described in Chapter 1, C/SIDE Fundamentals, properties are a system-wide
feature and every application object has some properties. Properties for forms
and controls are edited by opening the Property Sheet in the Form Designer (by
choosing Properties from the View menu). As you select the form or a control in
the form, the Property Sheet window will display the properties for the
selected object. The title bar of the Property Sheet window shows what kind of
object (form, text box, label, and so forth) is currently selected. The first line of
the sheet shows the ID if the object has one. (Note that the Property Sheet can
be scrolled vertically.)

Each field on the Property Sheet contains a value that you can set by entering a
value in the Value field on the Property Sheet. As soon as you leave the field
(by hitting Enter or by moving with the arrow keys) the property is updated. If
what you entered contains an error (for example, if you accidentally changed
the ID of one control to be the same as that of another control), the update will
not be accepted.

Default values are displayed in angle brackets (<>). If a property has a default,
you can reset it to the default by deleting the current value and then moving
out of the field. Notice that some properties do not have defaults–mainly
those that describe the position of the control within the form. These
properties are constantly updated by C/SIDE when the control is moved.

How Properties Are Inherited

Controls that have a direct relationship to table fields will inherit the settings of
those properties that are common to the field and the control. You can still
change the settings of these properties for the control, but you cannot overrule
the settings of certain field properties, namely those that concern data

110 Form and Control Properties

 Chapter 7. Designing Forms

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. On the other hand, you can
change properties like the caption–as 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 at the control level. The
advantage of using the lowest level (the field level) is that whenever the field is
used as the data source of a control, these settings will be used as defaults.
This ensures consistency.

Form Properties
The table below briefly describes some of the more important form properties.
All properties are described in detail in the online Reference Guide. You can get
context-sensitive Help for a property by opening the Property Sheet for a form,
placing the cursor on a property and pressing F1.

Property Name Use this property to...

ID set 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 C/SIDE dealer will
inform you about the numbers you can use.
Name give the form a descriptive name. The name does not have to be unique,
but you should give your forms unique names anyway, as they will be a lot
easier to identify and find by name than by ID.
Minimizable specify whether the user can minimize the form window.
Maximizable specify whether the user can maximize the form window.
Sizeable specify whether the user can resize the form window.
SavePosAndSize specify whether information about the user-made changes to the size and
placement of a form window will be saved. If it is set to Yes, this
information will be saved, and the next time the window is opened, these
values will be used. Otherwise, the designed values will be used.
Editable specify whether the user is allowed to edit controls in the form. If it is set to
No, no controls may be edited, even when their individual Editable
properties are set to Yes.
InsertAllowed specify whether the form can be used to insert records in the database.
ModifyAllowed specify whether the form can be used to modify records in the database.
DeleteAllowed specify whether the form can be used to delete records from the database.

Form and Control Properties 111

 Chapter 7. Designing Forms

Property Name Use this property to...

CalcFields specify a list of FlowFields that you want the system 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.
UpdateOnActivate specify whether you want the system to update the form when it is
activated.
SourceTable specify the source table of the form. Normally, you will have specified the
table when you first created the form. If you have created a form without an
underlying table, however, you can enter a table name here to bind the
form to a table.
SourceTableView create a view (what the user can see) of the source table for this form. You
can specify the key, sorting order and filter that the system will use.
SaveTableView specify whether the system will save information about which record the
user is viewing when the form is closed, the sorting order and the current
filter, and then reapply this information when the form is opened again.

General Properties for Controls

The table below briefly describes those properties that are common to several
types of controls. All properties are described in detail in the online Reference
Guide. You can get context-sensitive Help for a property by opening the
Property Sheet for a form, selecting a control, placing the cursor on a property
and pressing F1.

Property Name Use This Property to...

ID set the numeric ID of the control. The system assigns a sequential number by
default. If, however, you delete some 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 give the control a descriptive name.
Caption specify the text that the system displays for this control.
HorzGlue to anchor a control horizontally on the form. You can choose Left, Right or
Both. If you choose Both, the control will be resized when the form is resized.
VertGlue to anchor a control vertically on the form. You can choose Top, Bottom or
Both. If you choose Both, the control will be resized when the form is resized.
Visible specify whether the control will be 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 = No,
the child will not be visible, even if it has Visible = Yes.
ParentControl specify the ID of a parent control, thereby turning the control into a child.

112 Form and Control Properties

 Chapter 7. Designing Forms

7.2 Types of Controls

This section provides a brief overview of all controls that can be added to a
form. The list below is structured according to the broad categories into which
controls can be grouped.

Static controls
Static controls are controls that cannot change contents at run time.

Label A label is used for displaying text, most commonly for displaying the
caption of another control. In this situation the label is normally–and
conveniently–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 bitmap picture.

Shape A shape is a graphical element (line, circle, rectangle).

Data controls
Data controls are controls that can display the value of a C/AL expression, for
example the value of a table field or a variable (the simplest expression
perhaps is just the name of a table field or a variable) or of a ‘real’ expression.
The valid combinations of data control and data type are as follows

Control Valid data types

Check Box Booleans and BLOBs
Option Button All, except BLOBs
Text Box All
Picture Box Boolean, option, integer and bitmap BLOBs
Indicator Integer, decimal, date, time
Data controls must have a relation to data, defined as their SourceExpr
property.

Containers
Container controls are used for grouping other controls. Some properties of
the container overrule the same property in the contained controls: if the
container is not editable, no single contained control can be edited (even if it
individually has the Editable property set to TRUE).

Types of Controls 113

 Chapter 7. Designing Forms

Frame A frame is simply a rectangle into which other controls can be

‘dropped’. While you are designing, the frame and its contained controls can
be moved together, and a frame can have different border styles and colors.

Tab Control A tab control can be thought of as a kind of book with several
pages, or as several frames, where only one is visible at a time. The user can
switch between pages by clicking on tabs with captions.

Data Containers
Table Box A table box is a container, too, but a special kind. It contains
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 arise from vertically repeating each data
control. (If the table box displays records from a table, each row displays one
record.)

Other
Command Button A command button is not related to data–it performs an
action when it is ‘pushed’, that is, when it is clicked, or when Enter or Space 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 it, 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: it can perform an action when
you click it.

Subform A subform control is used for displaying a second form in a control

on a form (a main form), in order 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 purchases the customer has made.

114 Types of Controls

 Chapter 7. Designing Forms

7.3 Adding Controls

This section gives a few examples of how to add controls without using the
form wizards.

The Toolbox
You use the Toolbox to insert controls. The Toolbox is opened by choosing
Toolbox from the View menu. You select a specific tool by clicking the
corresponding icon.

Pointer Text Box

Label Option Button
Check Box Menu Button
Command Button
Frame
(not in use)
Picture Box
Image
Indicator
Shape
Subform
Tab Control
Table Box (not in use)

(not in use)
Lock Add Label

Note that some of these tools are not implemented in the present version of
C/SIDE, but that the icons are already present–they will, however, always
appear disabled.

When you click the Pointer tool, the state changes from insertion to selection.
(You can use this if, for example, you change your mind about inserting a
control.)

The Lock tool locks the current control selection. Normally, after you have
inserted a control, you have to select the type of control again before inserting
the next control. You can continue inserting controls of the same type without
having to select the tool again and again by turning Lock on (it is a toggle).

If Add Label is on (it is a toggle), all controls will have a label when you insert
them.

Adding Controls 115

 Chapter 7. Designing Forms

Adding a Text Box

If text boxes are related to database table fields, the easiest way to add them
to a form is to use the Field Menu. The Field Menu is a list of all fields in the
(table that is defined as the) SourceTable for the form. You can open the Field
Menu in the Form Designer by choosing Field Menu from the View menu. A text
box that has a specific field in the table as its SourceExpr (that is, has this field
as its underlying table field) can be added to the form as described below.

To add a text box:

1 Open the form in the Form Designer.

2 Open the Field Menu.

3 Select the field or fields from the Field Menu.

When you move the cursor into the design area, it will change into the Control
Insertion cursor.

(At present you need to activate the Form Designer window–for example by a
mouse click–before the cursor will change into the Control Insertion cursor).

4 Click in the design area for each selected field to insert a text box at the
cursor position.

If you selected more than one field, the text boxes will inserted aligned in a
column below the mouse position.

Each text box has these characteristics:

· It has the table field as its SourceExpr.

116 Adding Controls

 Chapter 7. Designing Forms

· 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, all properties that are both field properties and text box
properties have the value of the field property in the underlying table as a
default value.
· The text box has a label with a caption that defaults to the caption of the
text box.
The advantage of using the Field Menu to add text boxes with labels is that you
are effortlessly assured that naming and properties are consistent.

Beware that if the data type is anything but boolean, a text box will be created
automatically. If the data type is in fact boolean, a check box will be created.

Adding 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 way to add a calculated text
box, that is, a text box that is used to display a calculated value. It is also
possible to add an unbound text box and then, later on, bind it to a table field.

To add an unbound text box:

1 Open the form in the Form Designer.

2 Choose 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.

Now you have an unbound text box control on the form. Notice that no
characteristics were inherited and that the text box has no label.

Subsection Changing the Properties of a Control on page 121 explains how you
can bind the text box to a table field and add a label, and subsection Displaying
a Calculated Value on page 126 tells how you can use the text box to display a
value that is calculated on the fly.

Adding Controls 117

 Chapter 7. Designing Forms

Creating Labels That Display Descriptive Text

You can add a label that is not the child of another control to a form. You can
do this, for example, if you want to have a descriptive text on the form–it could
be instructions about using the form or other information that is static and not
related to any database table field.

To add a label:

1 Open the form in the Form Designer.

2 Choose the Label tool.

3 Move the cursor into the design area.

4 Click to create a label of the default size, or click and drag to create a label
of a different size.

5 As the label is not part of a control branch, it will be given a default name
and caption (like Control4). You can change the name and the caption on
the Property Sheet for the label (see Changing the Properties of a Control on
page 121).

118 Adding Controls

 Chapter 7. Designing Forms

7.4 Tools for Customizing Controls

In addition to the Property Sheet itself, there are two special tools available for
setting various properties of controls. They are: the Color tool, for selecting
color properties and border styles, and the Font tool, for setting font
properties.

Using the Color Tool

To start using the Color tool, open the View menu and choose Color. The tool
looks like this

When a control that has color properties is selected, you can pick colors for
foreground (text), background and border by clicking in the palette. The
corresponding properties are ForeColor, BackColor and BorderColor.

The check boxes Background and Border are used to toggle the display of
background color and display of the border on and off. The corresponding
properties are BackTransparent and Border (if these options are off, a
background or border color will not have any effect).

If the control has a border, the nine buttons at the bottom can be used to select
border style and border width.

Using the Font Tool

To start using the Font tool, open the View menu and choose Font. The tool
looks like this:

Tools for Customizing Controls 119

Chapter 7. Designing Forms

When a control that can display text is selected, you can set the font properties
by using the tool. You can enter the font name, the font size, attributes (bold,
italic and underline) and the horizontal alignment of the text (left, center, right
and general–general meaning that text is left-aligned and numbers are right-
aligned).

120 Tools for Customizing Controls

 Chapter 7. Designing Forms

7.5 Setting Control Properties

This section gives some examples of how to change the properties of a control,
and indicates some of the typical situations where this will be necessary.

Changing the Properties of a Control

If you have added controls without using the form wizards, you will often need
to change some properties of these controls. Even if you did use a wizard, you
may want to change some properties to meet specific requirements that the
wizards cannot consider.

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. The SourceExpr–source expression–is a C/AL
expression. It can just be the name of a table field, or it can be a more 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, Name and Caption will be set by default to
the name of the table field (unless the table field has a Caption: in this 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.

Notice the following dependencies:

· If you change the Caption property of the text box, the Caption property of
the label will be set to this value as a default (you will see that it is displayed
in angle brackets). If you change the Caption property of the text box again,
the Caption property of the label will also be changed again.
· On the other hand, if you change the Caption property of the label directly,
you will notice that the value that you enter is displayed without angle
brackets, signifying that it is no longer a default value. This means that if
you change the property of the text box, the value here will no longer be
updated.

Setting Control Properties 121

 Chapter 7. Designing Forms

Changing an Unbound Control into a Bound Control

An unbound text box–or other data control–can be changed into a bound
control quite easily.

All it takes is to change the SourceExpr into what 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 for a bound control, that is, they default to the
name of the table field.

This will not automatically add a label to the text box, but you can add one, as
described below.

Adding a Label to a Text Box

If you have created a bound text box by changing the SourceExpr for an
unbound text box, the bound text box will not automatically get an attached
label. You can add a label by adding a label control to the form and then
change the ParentControl property of the label from the default (undefined) to
the ID of the text box (which you can see on the first line of the Property Sheet
for the text box).

The control branch resulting from this operation can be selected and moved as
described in section 6.3, Selecting, Moving and Adjusting Controls.

Display Properties
Controls that you add to a form–either by using a wizard or manually–will have
a default set of properties that define how the control itself and the data it
displays are formatted. While this ensures a consistent visual design
throughout your applications, it cannot provide for all needs. You may
therefore have to change some properties that affect the way your forms and
their controls are displayed.

Controlling the Display of Numbers

This is a short description of properties that control the display of numbers.
Refer to the online Reference Guide for full descriptions.

DecimalPlaces This property (whose setting specifies both the minimum and
maximum allowed values) determines how many decimals are displayed and
how many can and must be entered. A typical situation where this property
would be used is when amounts are stored in the database with 5 decimal

122 Setting Control Properties

 Chapter 7. Designing Forms

places for higher precision, while you want the user to see only the customary
number of decimal places for the currency in question–for example 2. The
table field would then have the DecimalPlaces property set to 2:5, while the
DecimalPlaces property of the text box should be set to 2:2.

BlankNumbers You can choose from an option list whether a range of

numbers will be displayed or they will be blanked.

BlankZero The default is No. If you change it to Yes, zero values and booleans
that would have been displayed as a No will be blanked out.

Divisor The default is Undefined. If a number is entered, numeric values will

be divided with this number when they are displayed. Any remainder will be
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

This is a short description of properties that control formatting of data. Refer to
the online Reference Guide for full descriptions.

Format This property defines how the system formats 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. Finally, you can build your own formats to serve
special needs.

HorzAlign and VertAlign These properties define how data in a text box or a
caption on a label will be aligned horizontally and vertically, respectively.

MultiLine If this property is set to Yes, labels and text boxes can have
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. See subsection
Displaying More Than One Line of Text on page 126 for details.

PadChar This property specifies the character to 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 will be leading dots before
the data. The dots are placed according to the horizontal alignment of the data:
if left-aligned, the dots are placed to the right, if right-aligned, the dots are
placed to the left–and if centered, there will dots both before and after the
data.

Setting Control Properties 123

 Chapter 7. Designing Forms

If this property is set to Yes, the setting of PadChar will be overruled.

Properties That Control Input

This group of properties can be used to control user input, that is, restrict user
input to certain values or a certain length.

Numeric This property restricts input to numeric values only if it is set to Yes.

MinValue, MaxValue Sets a minimum or maximum value that the user can
enter.

ValuesAllowed Here you can specify the values that the user is allowed to
enter. Enter the values separated by semicolons, like 1;7;4711 or a;b;c.

CharAllowed Here you can enter characters that the user can enter. You can
enter a range, for example AZ, to limit entry to uppercase characters only, or
several ranges, for example amot, specifying two ranges: a to m and o to t.

NotBlank If this is set to Yes, then an entry consisting of nothing, one blank or
several blanks (spaces) will not be accepted–though a blank can be part of
string that contains other characters.

MaxLength The maximum number of characters that can be entered in a text

box.

AutoEnter If this is set to Yes, the system will accept a user entry 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, the user does not have
to press Enter.

PasswordText If this is set to Yes, user input will not be displayed, but shown
as asterisks (******).

Assisting the User

The ToolTip property allows you to assist the user by displaying text that
describes a control. You can also control the captions used in the title bar of a
form window.

ToolTip If you enter a text here, it will be displayed in a small pop-up window
whenever the mouse cursor rests on the control for a short while. The text is

124 Setting Control Properties

Chapter 7. Designing Forms

supposed to be a short, perhaps just one word, description of what the control
is used for.

DataCaptionField, DataCaptionExpr As mentioned in the table of form

properties above, you can control the label that is displayed on the caption bar
of the form window by using the Caption property. This is a static caption,
usually the name of the underlying table. By using DataCaptionField (either at
table level or at form level), you can select fields from the record whose
contents are displayed (and updated) in the caption bar as the user pages
through the table. With DataCaptionExpr (form only) you can create a C/AL
expression to be displayed in the caption bar. The expression is reevaluated
when the user selects a new record or the present record is changed. The
online Reference Guide contains further explanations.

Notice that ...

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
if the user-selectable option Status Bar (choose Options... from the View
menu) is set to Yes, the caption of text boxes and check boxes will be displayed
in the status bar together with the current data contents of the control (if any)
when the control gets the focus.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting Control Properties 125

 Chapter 7. Designing Forms

7.6 How to Use Controls in Applications

Displaying More Than One Line of Text

If a database table contains very large fields, lengthy descriptive texts for
example, using the standard one-line text box is not a very good way to
present this information. Instead, you can customize a text box to wrap text
into multiple lines.

To create a multiline text box:

1 Open the form in the Form Designer.

2 Choose the text box and enlarge it vertically by resizing.

3 Open the Property Sheet for the text box and set the MultiLine option to Yes.

4 Run the form. Entering or editing text will still take place on one line that
scrolls horizontally. When the 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 character, and the user can insert line breaks (‘hard newlines’)
by embedding a backslash character (‘\’) in a text string. (To display a
backslash, enter ‘\\’.)

5 You may have to experiment with the vertical resizing of the text box to find
the size that suits your purpose best.

Displaying a Calculated Value

A control can be used to display a value that is not stored in the database but
calculated as the form is displayed. One situation where this could be useful is

126 How to Use Controls in Applications

 Chapter 7. Designing Forms

when all the information needed for the calculation is actually stored in the
database, and–conforming to the rules for a relational database system–the
calculated value is not stored separately. However, the users of the application
do sometimes need this value. Adding a calculated control can give this
information, without violating the rules for good database design.

To display a calculated value:

1 Open the form in the Form Designer.

2 Choose a tool that inserts an appropriate data control (check box, text box,
indicator) in the Tool Box.

3 Move the cursor into the design area.

4 Click to add the control.

5 Open the Property Sheet for the control. Type the expression you want as
the SourceExpr property.

Example

You have designed 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
actually has to pay. Add an unbound text box and enter as the SourceExpr:

"Unit Price" - ("Unit Price" * "Employee Discount Rate" / 100)

Presenting a Set of Options

A recurring task in application programming is to present the user of the
application with a fixed set of options to choose from. For example, in a
program where the user frequently has to enter the title of a contact, it could
be a list of titles. The field or variable that is the SourceExpr of the control must
have type Option, and the options must have been entered as the OptionString
property of the field or variable.

In C/SIDE you can present these options in several ways. The following
sections show two different approaches.

Creating a Drop-Down List of Options

The list of options can be presented as a drop-down text box, as in the picture
below:

How to Use Controls in Applications 127

 Chapter 7. Designing Forms

To create a drop-down option list:

1 Open the form in the Form Designer.

2 If the option text box is based on a table field, open the Field Menu and
highlight the field. Otherwise, proceed to create an unbound text box.

3 Choose the text box tool; then click in the design area to create the text box
(if the text box is based on a field that you have selected in the Field Menu,
just click in the design area).

4 If the text box is unbound, bind it to the variable now by entering the name
of the variable as the SourceExpr of the text box.

When you run the form, the text box will have the drop-down symbol attached
(h), and you will be able to open the list by clicking this symbol.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
you can enter only options that have been defined on the Property Sheet of the
field or variable. The first option will be displayed in the text box. If the
OptionString property has a blank as the first option, the text box will
accordingly be blank. This does not mean that options that are not in the
OptionString can be entered.
In the OptionString property of the control, you can select a subset of the
options already defined for the field–you cannot add options.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating an Option Button Group

Another way of presenting a set of options is as an option button group. The
functionality will not be any different from that provided by a drop-down list,

128 How to Use Controls in Applications

Chapter 7. Designing Forms

but the visual presentation is, of course, quite different. An option button
group looks like this:

The advantage of using an option button group is that the user of the
application can see all the available options and the currently chosen 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 does.

To add an option button group:

1 The OptionString property of the field or variable must be defined, as

described above.

2 Open the form in the Form Designer.

3 Add an option button for each option in the OptionString of the field or
variable (the option buttons must be added as unbound controls).

4 Enter the field or variable as SourceExpr in the Property Sheet for each
button.

5 Enter one of the options from the OptionString as the OptionValue property
for each button.

Each button has the OptionValue as its caption. Because the option buttons
have the same source expression, only one of them can be chosen at a time.
When you choose an option by clicking on the button, any previously-chosen
button will be marked as not chosen.

How to Use Controls in Applications 129

 Chapter 7. Designing Forms

Example

In the illustration above, the option button group has been embellished by adding two frames: the
group is contained by a frame with a raised border and no caption. The other frame is actually the
–
‘Title’ caption with the TopLineOnly property set to Yes, and Caption property set to Title.

Using a Check Box to Display Booleans

A check box control is a handy way of displaying data of type Boolean. In a text
box, boolean values will be shown as Yes and No. In a check box, Yes will be
displayed as a check mark, while No will be displayed as a blank.

To add a check box:

1 Open the form in the Form Designer.

2 If the check box will have a direct relationship to a table field, select the field
in the Field Menu. Otherwise proceed to create an unbound check box.

3 If you want a label attached to the check box, click the Add Label tool (check
boxes do not by default have labels).

4 Choose the Check Box tool; then click in the design area to create the check
box (if you have selected a field of type Boolean from the Field Menu, you
only have to click in the design area).

5 If the check box is unbound, bind it to the variable now by entering the
name of the variable as the SourceExpr of the text box.

130 How to Use Controls in Applications

 Chapter 7. Designing Forms

Creating and Using Command Buttons

Command buttons are useful for a number of purposes. If you have used a
wizard to create forms, you will have noticed that a Help button has been
added to all forms. Other common uses are Yes and No buttons in contexts
where the user must decide whether a certain task will be performed or not.
Still another use is to launch another form, or even another program.

To add a command button:

1 Open the form in the Form Designer.

2 Choose the Command Button tool; then click in the design area to add the
command button.

This will create the command button. The next step is to define the action
associated with the button.

3 Open the Property Sheet for the command button. The PushAction property
specifies what happens when the command button is pushed.

4 Open the drop-down list in the PushAction property value field. You will see
this list of possible actions:

5 A common action would be to run another form. Choose RunObject.

6 In the RunObject property, open the look-up table of system objects, and
choose the object you want to run when the command button is pushed.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
not all settings of the PushAction property require additional information.
Some do, such as RunSystem, while others, such as Yes or No, do not.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

How to Use Controls in Applications 131

 Chapter 7. Designing Forms

While this method of adding an action to a command button is easy to use, it

does have some limitations. For example, you cannot pass parameters. A more
powerful method is to use the OnPush trigger for the button. Triggers are
explored in Chapter 8, Extending the Functionality of Your Forms.

Containing 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: during
design, they are moved when the frame is moved, with their relative positions
intact; if the frame is invisible, all contained controls will be invisible too. A
frame can have a border that can be raised or sunken. This feature can be used
to distinguish a group of controls (such as a group of option buttons) visually.

To create a frame with contained controls:

1 Open the form in the Form Designer.

2 Choose the Frame tool; then click and drag in the design area to create a
frame.

3 Create the controls you want to be contained by the frame in the usual way,
placing them inside the frame as you add them to the form.

4 Set the properties of the frame to suit your purpose.

A common change will be inhibiting display of the caption by setting the

ShowCaption property to No. By default, the border style is Raised. If the
purpose of the frame is not to distinguish the contained controls, you can set
the Border property to No, meaning that no border will be displayed.

132 How to Use Controls in Applications

 Chapter 7. Designing Forms

When an existing control is dragged inside a frame and dropped, it will be

contained in the frame. When a control is dragged outside a frame, it will no
longer be considered to be contained by the frame.

If a container is resized and thereby overlaps existing controls completely,

these controls will be contained.

If a frame is deleted, all controls contained by it are deleted. See Sizing and
Resizing Controls on page 104 for details on resizing container controls.

Adding Shapes and Pictures

You can add shapes (graphical elements) and bitmap pictures to forms in order
to provide information (pictures of products, for example), in order to
emphasize information (by adding a shape that makes some controls stand
out)–or for purely decorative purposes.

Using Shapes
The ShapeStyle property lets you choose from a number of shapes: rectangle,
rounded rectangle, oval, among others. You can adjust the width and the color
of the lines that the shapes are composed from by changing the BorderWidth
and BorderColor properties.

To create a shape:

1 Open the form in the Form Designer.

How to Use Controls in Applications 133

 Chapter 7. Designing Forms

2 Choose the Shape tool from the Toolbox

3 Click and drag in the design area to add a shape of the desired size.

4 Choose a ShapeStyle and appropriate width and color in the Property Sheet
for the shape.

Adding a Static Picture as an Image

The simple way of adding a bitmap picture is to add it as a control of type
image.

To add an image:

1 Open the form in the Form Designer.

2 Choose the Image tool from the Toolbox.

3 Click and drag in the design area to create an image control.

4 Open the Property Sheet for the image control, and enter the file name of
the bitmap in the Bitmap property.

Beware that the bitmap is not referenced but actually imported. This has the
advantage that you don’t need any external files for your application. On the
other hand, if you make any changes to the bitmap during application
development, you must update the imported copy by opening the Property
Sheet, selecting the Value field of the Bitmap property and pressing F2. This
will cause a reevaluation of the field, thus forcing the bitmap to be imported
again. The size of the bitmap is limited to 32 Kb.

134 How to Use Controls in Applications

 Chapter 7. Designing Forms

Adding a Data Dependent Picture as a Picture Box

Adding a bitmap in a picture box control instead of in an image control
provides some advanced possibilities. While the image control is static, the
picture box control is dynamic: provided you create a list of bitmaps, a bitmap
from this list can be chosen at run time (the total size of the bitmaps in the list
is limited to 32 Kb).

A picture box provides another advantage: 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 picture box:

1 Open the form in the Form Designer.

2 Choose the Picture Box tool from the Toolbox.

3 Click and drag in the design area to create a picture box control.

4 Open the Property Sheet for the picture box control.

To create a list of bitmaps from which one can be selected at run time for
display, follow these steps:

1 Enter a comma-separated list of the file names of the bitmaps you want to
use. The system provides a series of standard bitmaps that can be chosen
by entering a number–see the online Reference Guide entry on Bitmap for
details.

2 The value of SourceExpr determines which bitmap will be chosen by the

system: the first in the list has number 0, the second number 1, and so forth.
If SourceExpr evaluates to a value outside the range of bitmaps, no bitmap
will be displayed.

To display a picture stored in a BLOB field, do this:

Enter the field name of the BLOB field as the SourceExpr property. Do not
enter a BitmapList property.

Pictures on Command, Menu and Option Buttons and in Check Boxes

Command buttons, menu buttons, option buttons and check boxes all have the
capability of displaying a bitmap picture instead of–or in combination with–a
caption.

How to Use Controls in Applications 135

 Chapter 7. Designing Forms

They all have a property called Bitmap. Here you can enter the filename of a
bitmap. The maximum size of the bitmap is 32 Kb, and it is actually imported,
not referenced (thus if you change the original bitmap, you will have to
reimport it).

They also have a property called BitmapPos, where you can select the
alignment of the bitmap within the control. This is especially useful when you
are combining a caption and a bitmap: then you could right-align the caption
and left-align the bitmap, like the command button in picture below.

Using a bitmap on a button or a check box can in some situations make the
user interface more intuitive: a well-chosen picture may be easier to remember
and use than a label.

Using an Indicator to Display Values

The indicator control provides a way of displaying values graphically, as an
analog gauge. A minimum and a maximum value must be defined, to make it
possible for the system to calculate the scale of the indicator. If you do not
provide these values, the system uses default values (see the online Reference
Guide for details).

136 How to Use Controls in Applications

 Chapter 7. Designing Forms

To create an indicator:

1 Open the form in the Form Designer.

2 Choose 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 you want to control the
indicator.

4 Set the MinValue and MaxValue properties of the Indicator.

5 Set the Percentage property to choose whether or not the indicator will
display percentages. If this property is Yes, the “23%” shown in the picture
above will be displayed–otherwise, it will not. 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).

Creating a Tab Control

A tab control is useful when you are designing a form that is based on a table
with many fields. Instead of creating a large form, cluttered with controls, you
can group controls together on pages that the user can bring to the front by
clicking the tabs.

You can use a form wizard to create a form with a tab control.

To create a tab control manually:

1 Open the form in the Form Designer.

2 Choose the Tab Control tool and click and drag in the design area to create a
tab control.

3 Open the Property Sheet for the tab control, and create the pages you need
by entering a name for each page as a comma-separated list in the
PageNames property. The names will be used as captions on the tabs.

4 The tabs are created while you are in the Form Designer. You can select
pages by clicking the tabs.

5 Add controls on the pages. You can think of each page in a tab control as a
frame and add controls as you would in a frame.

How to Use Controls in Applications 137

 Chapter 7. Designing Forms

Creating a Table Box

A table box is useful when you need to display many records from a database
table at the same time. A table box contains columns and rows, and the user
can move through the records, either by clicking navigation buttons (as) or by
using arrow keys and PageUp and PageDown. If the form is too narrow to
display all columns, a horizontal scroll bar will automatically be added to the
control.

You can use a form wizard to create a form with a table box.

To create a table box manually:

1 Open the form in the Form Designer.

2 Choose the table box tool, and click and drag in the design area to create a
table box.

3 If the form is not related to a table, you can establish a relation now, by
setting the SourceTable property of the form to the name of the table.

4 Open the Field Menu.

5 Select the fields you want in the table box from the Field Menu and click
inside the table box. A column will be 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.

138 How to Use Controls in Applications

Chapter 8
Extending the Functionality of Your
Forms

This chapter explores form design further,

including sections on forms related to multiple
tables, on creating menus and on writing C/AL
code in triggers.

· Main forms and Subforms

· Looking Up and Validating
· Drilling Down
· Launching One Form from Another
· Menus and Menu Buttons
· Triggers
 Chapter 8. Extending the Functionality of Your Forms

8.1 Main Forms and Subforms

As described in Chapter 2, Designing a C/SIDE Application, 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, suppose 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, for example the address of the customer, is per order, while other
information, for example 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: one, a header table, with the general order
information, another, a lines table, with the information about each item. There
is one-to-many relationship between the tables.

However, the users of the application need to view information from both
tables at the same time: the header information together with the lines, like
this

Although this looks like a normal form it is, in fact, two forms.

The main form is the one side of the one-to-many relationship; in the example,
it is based on the Sales Order Header table. The subform is the many side of
the relationship; in the example, it is based on the Sales Order Line table.

140 Main Forms and Subforms

 Chapter 8. Extending the Functionality of Your Forms

When the user selects a sales order header in the main form, the subform is
updated to display only sales order lines pertaining to this sales order header:
there is a link between the main form and the subform that keeps the
information synchronized.

Designing the Main Form

There are no special procedures involved in designing a form that will be used
as the main form in a main form/subform relationship: it is designed as any
other form.

In order to add a subform, you will add a subform control. The subform control
establishes the link between the main form and the subform, but it is not a
form in itself. 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 below. If you are going to create a new form to use as a subform, it
may be more convenient to create the subform first. How to do this is
described in the next subsection.

To create the main form in a main form/subform relationship:

1 Open the form in the Form Designer.

2 Select the Subform tool, and click and drag in the design area to create the
subform control.

3 Open the Property Sheet for the subform control.

4 Enter the name of the form that you want to use as a subform as the
SubFormID property (or use the lookup button to choose from a list of all
forms).

5 Enter the expression that links the two tables (for example the field that is
common for the tables) as the SubFormLink property. There is an assist-edit
function available to assist you (click the k button to open the assist-edit
window). Choose the field name from the many side of the relationship (the
subform table) as the Field. Then choose FIELD as the Type of the
relationship. Finally, choose the field from the one side of the relation (the
main form table) as the Value.

Main Forms and Subforms 141

 Chapter 8. Extending the Functionality of Your Forms

6 In the SubFormView property, you can specify the key, sort order and table
filter you want the system to apply to the table when it is displayed in the
subform (it is not mandatory to enter anything).

Example

In the SubFormLink property, you can choose other types of link than FIELD. 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 (as, for example, 10|30..40).

Designing the Subform

There are no special requirements for a subform, that is, it is exactly like any
other form in the system. However, the form is going to be used to display the
many side of a one-to-many relationship, and not all forms are equally useful
for this purpose.

The typical choice is a tabular form, that is, a form with a table box. See
Creating a Table Box on page 138 for details. The table box should fill out the
form completely, and 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–in this way, the subform and the table box will be resized when the main
form is resized.

Hints and Advice

Even if creating a form with a subform is not different from creating controls on
forms in general, you may have to perform some experiments before you find
the best way to do it. Here are some hints and advice to help you along:

· It can be difficult to get the sizing of the subform control on the main form
and the size of the subform itself right. You should finish the design of the
subform first. Get the values for width and height of the form from the
Property Sheet. Then, in the main form, click and drag a subform control of
any size. In the Property Sheet, insert the width and height of the subfom as
the width and height of the subform control.
· Generally, if the subform is a tabular form, it will look better if you let the
table box completely fill out the form vertically–this way there won’t be
extra space around the table inside the subform control–and set the
HorzGlue and VertGlue properties to Both.

142 Main Forms and Subforms

Chapter 8. Extending the Functionality of Your Forms

· If the subform is a tabular form, you should size the form to show only a few
records at a time. Then, in the main form, set the VertGlue and HorzGlue
properties of the subform control to Both. The user can resize the main form
vertically and horizontally, and the subform will be resized along with it:
more records and fields will be displayed.

Main Forms and Subforms 143

 Chapter 8. Extending the Functionality of Your Forms

8.2 Looking Up Values and Validating Entries

The previous section described how to create a main form and a subfom in
order to display data from a one-to-many relationship. The main form was
bound to the table on the one side of the relationship; the subform was bound
to the many side.

Suppose, instead, that you are designing a form that is bound to a table
containing information about customers. Some of this information is unique
for each customer, while other information is not. The names and addresses of
the customers are unique, but suppose 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 addresses of these
shippers in the customer records.

Instead, you would create a Shipper table, and use a Shipper Code field to
create a link between this table and the Customer table, storing only the
shipper code in each customer record, and storing all other information about
the shippers in the Shipper table.

Shipper Record Customer Record

Shipper Code Number

Name Name

Address Address
Customer Record
Phone ...
Number
.... Shipper Code
Name

Address
Customer Record

Number ...

NameShipper Code

Address

...

Shipper Code

144 Looking Up Values and Validating Entries

Chapter 8. Extending the Functionality of Your Forms

This is, in fact, the many side of a one-to-many relationship: while each
customer can be associated with only one shipper, a shipper can be associated
with many different customers. A main form/subform is not applicable here (it
would be, though, if you were to design a form to display information about
the shippers–then the subform could display a list of customers that use each
shipper).

There are two things you must consider when creating the customer form (and
table):

· Do you want to provide the user with an easy way of entering 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, the users will have
to memorize the shipper codes, and they may easily enter a code that does not
exist in the Shipper table. If the tables are related, the system provides a
lookup function into the Shipper table, so that the user can press F6 or click a
lookup button (p) and select the 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 by defining the relationship, either at the table level,
as a property of the shipper code field in the Customer table, or at the form
level, as a property of the text box displaying the shipper code on the Customer
(main) form.

If you want to make certain that the user does not enter non-existent shipper
codes into the Customer table, the system can validate the entries against the
Shipper table. The ValidateTableRelation property, either of the field (at table
level) or of the text box (at form level), governs whether entries are required to
exist in the Shipper table.

Apart from simply asserting 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 of fields in both tables (for example, you can
have the system check whether the shipper allotted to a customer operates at
all in the customer’s country). To do this, you will have to create the validation
rule by writing C/AL code in the OnValidate trigger of the control on the main
form.

Looking Up Values and Validating Entries 145

 Chapter 8. Extending the Functionality of Your Forms

A form with a lookup on the Shipping Agent field looks like this when the
lookup function has been activated:

Defining the Table Relation

A mentioned above, the relationship to a table can be defined in two different
places. In both places, as part of a table description or as part of a form
description, the relationship is defined in the TableRelation property of the
field or control. For the application user, there will be no functional difference
between a table relationship defined at the table level and a table relationship
defined at the form level. There is a difference, though, when you are designing
an application. If the relationship is defined at the table level, all text boxes in
forms that have a direct relationship to the field will have the lookup
functionality–with no effort required from the person designing the forms. You
can suppress the function by setting the Lookup property of the text box
explicitly to No.

To define a table relationship:

1 Open the Property Sheet for the field or the control.

2 In the Value field of the TableRelation property, click the assist-edit button.

3 In the assist-edit window, enter the name of the table to lookup into in the
Table field (or choose from list that appears when you click the lookup
button).

146 Looking Up Values and Validating Entries

 Chapter 8. Extending the Functionality of Your Forms

4 In the Field field, enter the name of the field in the table (or choose from the
lookup list).

You can use the Condition and the Table Filter fields to create a more advanced
relationship than this basic one.

By using the Condition field, you can, for example, lookup to 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 be validated against the contents of a field in a related table quite
easily. If you set the ValidateTableRelation property to Yes–either at field level
or at 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 the way a lookup functions than you can achieve
by using conditions and filters, you can write C/AL code in the OnLookup
trigger. In this way you can bypass the default lookup function completely and
write your own.

The rules for determining which lookup function is performed are these: a
trigger at the form level takes precedence over one at the table level. Both of
these take precedence over the system default action.

Defining a Lookup Form

When you are using the system lookup function, you will have to 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 defined that will be used for looking up into
the table, by setting the LookUpFormID table property–or a form can be
defined by setting the LookUpFormID of the control for which the lookup is
provided. If both properties are set, the form defined as a control property will
be used.

Looking Up Values and Validating Entries 147

 Chapter 8. Extending the Functionality of Your Forms

Pay attention to the fact that if no lookup form is defined (either at table level
or at form level), then although the text box will have the lookup button (p)
attached, a lookup will not be performed when the button is clicked.

If you are writing your own lookup function in the OnLookup trigger, you will
have to explicitly run a form by using the RUNMODAL C/AL function.

Hint
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If you always design a basic tabular form (fast and easy, using the wizard) for a
table, and enter this form as the LookupForm (and DrillDownForm) of the table,
you will never forget to provide a lookup form. If you later on decide that this
form is not adequate for some lookups, you can add customized forms as
control properties.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Permanent Assist
This is a control property. If it is set to Yes, the lookup button will be
permanently displayed; otherwise, it will be displayed only when the control
has the focus.

Looking Up in the Current Table

By setting the Lookup property of a text box to Yes, you can provide a lookup
to the same table (the source table of the form, that is). This is intended to
provide the user with an easy way of selecting a record to work with. In effect,
the lookup provides a list of all records in the table; the user can select a
record from the list, which will then become the current record.

A lookup form must be defined, either at table or at form level, just as when the
lookup is to another table. You cannot set conditions and filters, however (as
you can when the lookup is to another table). The default behavior is to display
all records in the table. If you need to change this, you will have to write your
own lookup function in the OnLookup trigger.

If a lookup into a related table is defined–regardless of how the relation is

defined–setting Lookup to Yes will be overruled. On the other hand, if Lookup
is (explicitly) set to No (as opposed to its default value <No>), no lookups,
including to related tables, will be performed.

You can provide the same functionality by using the LookupTable action
(applicable to command buttons and menu items). In this way you can provide

148 Looking Up Values and Validating Entries

Chapter 8. Extending the Functionality of Your Forms

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.

Looking Up Values and Validating Entries 149

 Chapter 8. Extending the Functionality of Your Forms

8.3 Drilling Down to the Underlying Transactions

FlowFields were introduced in Chapter 3, Table Fundamentals. When a text box
is based on a FlowField, you will see that a drill-down button (o) automatically
is attached to the text box. When the user clicks this button (or presses Shift
F6), the transactions that the system used to calculate the value of the
FlowField will be displayed.

In the first picture below, the Chart of Accounts, you can execute a drill-down
function in the Net Change field–a FlowField that summarizes transactions in
this account. The next picture shows the form that is displayed when that
particular drill-down is performed–a detailed list of the transactions.

The drill-down facility is provided whenever a text box is directly related to a

FlowField–you do not have to do anything special when designing the form
except to make certain that a DrillDownFormID is defined (as for lookups–see

150 Drilling Down to the Underlying Transactions

Chapter 8. Extending the Functionality of Your Forms

Defining a Lookup Form on page 147), either at the table level or at the form
level.

Drill-downs resemble lookups in many ways, and with them you can do most of
the things that you can do with lookups–one exception being that drill-downs
pertain only to FlowFields, which have to be defined when the table is
designed.

You can customize a drill-down in these ways:

· You can disable the drill-down altogether by setting the DrillDown property
of the text box explicitly 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, by setting the
PermanentAssist property of the text box. Yes means that the button will
always be displayed, and No means that the button will be displayed only
when the text box has the focus.
· You can change the drill-down behavior altogether by writing C/AL code in
the OnDrillDown trigger of the table field or the control. In this case you
have to run a form explicitly from your trigger code, as the system does not
perform any part of the default drill-down and does not display a form
automatically.

Drilling Down to the Underlying Transactions 151

 Chapter 8. Extending the Functionality of Your Forms

8.4 Launching Another Form

When you provide a lookup function for selecting values in a related table, you
will typically display only a subset of the fields in the lookup table.

In some situations, however, it would be convenient to be able to update other

fields than those displayed on the lookup form in the related table without
closing the current form. Suppose a user is taking orders by phone. It is
convenient to use a lookup function on the sales order forms to find the
customer numbers as customers call in. But what if a customer calls in to order
something–and mentions that he has moved to a new address? It would be
time consuming–and annoying–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 is to provide a way to launch 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.

In order to launch another form, you can add a control that has a PushAction
property and run the customer form with parameters to select the correct
record from the Customer table whenever the user ‘pushes’ the control. You
can use command buttons, menu items, check boxes or option buttons.

To add a command button that launches a form, follow these steps

1 Add a command button (the procedure is described in Chapter 7).

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
you want to launch. As you can use RunObject to run any object, you have to
specify the type of object (Form, Codeunit, and so forth). You can choose the
object from the lookup list that is provided (in this case, the type of the
object is inserted automatically).

4 Set the RunFormLink property to establish the link to the form you want to
launch. Use assist-edit (click k ) to create the expression. First, select a field
from the table underlying the form you going to launch. Choose FIELD as the
type of the relationship. Finally, as the Value parameter, select the field in
the table underlying the current form that must match the value in the other
table.

152 Launching Another Form

 Chapter 8. Extending the Functionality of Your Forms

8.5 Designing Menu Buttons

While command buttons are a convenient way of adding functionality to forms,
an excess of buttons will clutter the forms and impair their visual design. If you
need to use many command buttons, you should consider creating menu
buttons instead.

When a menu button is pushed, a menu is opened:

Each line in a menu is called a menu item. A menu item can:

· Perform an action when clicked. This can be an action from the same set of
actions as command buttons (see the online Reference Guide for a list), or it
can be an action written in C/AL, as menu items have OnPush triggers just
like command buttons.
· Contain a submenu that is opened when the line is clicked.
· Be a separator–a line used for grouping items in a menu together.
A menu is created in two steps. First you add a menu button to your form. This
part is exactly the same procedure as adding a command button. Then you
open the Menu Designer for the menu button and create the menu items.

Designing Menu Buttons 153

 Chapter 8. Extending the Functionality of Your Forms

Adding a Menu Button to a Form

To add a menu button:

1 Open the form in the Form Designer.

2 Choose the Menu Button tool, then click in the design area to add the menu
button.

3 Select the menu button and open the Property Sheet for the menu button.
As a menu button does not have a relation to data–field or variable–Name
and Caption are set to default values (like Control7). Change the Caption to
an appropriate text. If the text contains an ampersand (&), the system
interprets the following letter as an access key.

Adding a Menu Line to a Menu

When you have created and modified a menu button as described above, you
can add lines to the menu that is displayed when the button is pushed.

To add a menu line:

1 Select the button and open the Menu Designer while the button is selected.
(Choose View -> Menu Items.)

154 Designing Menu Buttons

Chapter 8. Extending the Functionality of Your Forms

2 The first field, Visible, is by default set to Yes. Leave it like this.

3 Add lines by filling out the Caption field. If you do not create an access key
yourself (by embedding an ampersand in the Caption text), the system will
automatically use the first letter of each Caption as an access key. If you add
menu lines where some captions start with the same letter, you must set the
access keys yourself to avoid overloading certain ones.

4 If you want, you can define a shortcut key (accelerator key) by entering the
name of the key in the ShortCutKey field. Keys are entered as follows

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

An accelerator key is active as long as the focus is on the form that the menu
button is a child of. Beware of accidentally overloading some key
combinations so that they perform different actions when different forms
have the focus–this could confuse the user. Also beware of using
accelerator keys that the system already uses.
5 Enter the action for the menu item in the Action field. You can use the drop-
down list that is available to choose from among the same actions as for a
command button. You can also write C/AL code in the OnPush trigger of the
menu item.

6 If you have chosen RunObject, you can define the object (form, report,
codeunit) in the Object field. There is a lookup function available to help you

Designing Menu Buttons 155

 Chapter 8. Extending the Functionality of Your Forms

select the object. For other parametrized actions (for example RunSystem)
you have to set the parameters in the Property Sheet of the menu item (see
below for details).

Adding Other Menu Items

In addition to lines that perform actions, menus can contain separators and
lines that are submenus–that is, lines that open up another menu when you
click them.

Separators A separator is a horizontal line in a menu that cannot be selected

or perform any action. It helps you group items on a menu.

To add a separator to a menu, click the Separator button in the Menu Designer.
The separator will be inserted after the currently-selected line.

Submenus and Menu Levels Menu items can be nested, that is, when you
click a line on a menu, another menu can open.

Submenus are defined in the Menu Designer. When an item is selected, you
can indent it by clicking the right-arrow button. An indented item becomes a
menu item on a submenu. If you open the Property Sheet for a menu item, you
will see that when first created, menu items have the MenuLevel property set
to a default value of zero. As items are indented, the MenuLevel is set to 1, 2, 3
and so forth–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 you must follow when creating
submenus:

· If there are any items at all in a menu, there must be at least one item with
MenuLevel 0 (zero).
· Each MenuLevel can be at most one 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 becomes a submenu, and the item with
MenuLevel 1 becomes an item on this submenu. A menu line that is a
submenu cannot have any action associated with it.
· There can be up to 10 menu levels (numbered from 0 to 9).

156 Designing Menu Buttons

 Chapter 8. Extending the Functionality of Your Forms

· If the MenuLevel reverts to lower numbers (less indentation), menu items

will from then on become items in the previous menu at the level indicated
by the MenuLevel.
· Separators cannot be submenus and separators have to separate items at
the same level, that is, you cannot put a separator as the first or last (or
only) item in a menu or submenu.

Check Marks on Menu Items

Menus in Windows programs habitually employ a special feature: for menu
items that act as toggles, the on/off state is indicated by the presence or the
absence of a check mark next to the item in the menu.

The SourceExpr property of a menu item is used for controlling whether a

check mark is displayed or not. Initially, the SourceExpr property is undefined.
You can define it to a valid C/AL expression that evaluates to a boolean. The
check mark appears when the value is TRUE.

You can see how this feature can be used in C/SIDE itself. In the Format menu,
the Snap to Grid menu item is a typical example: it can either be on or off.
When it is On, the check mark is displayed.

Designing Menu Buttons 157

 Chapter 8. Extending the Functionality of Your Forms

8.6 Form and Control Triggers

While the system interprets and acts upon many events in a predefined way,
certain actions–such as opening a form or pushing a command button–causes
the system to execute a user-definable C/AL function (the event triggers the
function). You will typically use triggers to do advanced validation, to initialize
variables in a non-trivial way or perhaps to format text boxes according to the
value of a field or control. In short: you use triggers whenever the system
default behavior does not suit your purpose.

Overview of Form Triggers

These triggers pertain to forms in C/SIDE

Form trigger name Executed when...

OnInit the form is loaded, but before controls are available.
OnOpenForm the form has been initialized (controls are available).
OnQueryCloseForm the form is about to close, but before OnCloseForm. If this trigger
returns FALSE, the form is not closed. The intended use is for asking
the user if he or she really wants to close the form.
OnCloseForm the form is about to close, and after OnQueryCloseForm.
OnActivateForm the form is activated, that is, when the form becomes the active
window.
OnDeactivateForm the form ceases being the active window.
OnFindRecord 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 the system determines how to select the next record, for example
after a user pressed PageDown (in a card form).
OnAfterGetRecord a record has been retrieved but not yet displayed.
OnAfterGetCurrRecord the current record is retrieved. In a table box. OnAfterGetRecord is
called for all the records displayed, while this trigger is called for the
current record.
OnBeforePutRecord a record is about to be saved.
OnNewRecord a new record has been initialized but not yet displayed.
OnInsertRecord a new record is about to be inserted in the table.
OnModifyRecord a record is about to be modified in the table.
OnDeleteRecord a record is about to be deleted from the table.
The table only sketches out the main purpose of each trigger. Refer to the
online C/SIDE Reference Guide for extensive descriptions and details.

158 Form and Control Triggers

 Chapter 8. Extending the Functionality of Your Forms

Notice that ...

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
the last three triggers in the table–OnInsertRecord, OnModifyRecord,
OnDeleteRecord–correspond to triggers at table level. If you use triggers at
both form and table level, the triggers at form level will be executed first, then
the triggers at table level.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview of Control Triggers

Depending on the type of a control (see Chapter 7), controls have a varying
number of triggers. Static controls and container controls do not have any
triggers at all, while text boxes have a full range. Other data controls and data
container controls have a subset of the possible triggers. Controls that can be
pushed–such as a command button or menu item, and also a check box–have a
special trigger to handle this.

The following table outlines the full range of triggers. The column at the right
indicates the controls for which the trigger is relevant.

Control trigger name Executed when... Controls

OnActivate the control is activated. 1,2,3,4,5,6,7,8
OnDeactivate the control is deactivated. 1,2,3,4,5,6,7,8
OnFormat the control is about to be updated. 5
OnBeforeInput the control is selected for input and before any input 5
is actually entered.
OnInputChange the user is entering data. This trigger is repeatedly 5
executed, after each keystroke.
OnAfterInput the user finishes input. 5
OnPush the control is pushed. 1,3,4,9
OnValidate the control loses focus. 3,4,56,7
OnAfterValidate the value entered has been validated. 3,4,5,6,7
OnLookup the user requests a lookup (by clicking a lookup 5
button or pressing F6).
OnDrillDown the user requests a drill-down (by clicking a drill- 5
down button or pressing Shift F6).
OnAssistEdit the user requests assist-edit (by clicking an assist- 5
edit button or pressing Shift F2).

Controls are
1 - command button, 2 - menu button, 3 - check box, 4 - option button, 5 - text box, 6 -
picture box, 7 - indicator, 8 - subform, 9 - menu item

Form and Control Triggers 159

 Chapter 8. Extending the Functionality of Your Forms

The table only sketches out the main purpose of each trigger. Refer to the
online C/SIDE Reference Guide for concise descriptions and details.

Notice that ...

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OnValidate is also a field trigger at the table level. If both triggers (field and
control) are defined, the field trigger is executed before the control trigger (and
the system default validation before anything else).

OnLookup is also a field trigger at the table level. The flow is different here:
when a lookup is requested, the system executes the control lookup trigger, if
defined, in place of the field lookup or system default. If no control lookup
trigger is defined, a field lookup trigger (if defined) replaces the system default
lookup function.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

How to Define and Modify Form and Control Triggers

When you want to define a function to be triggered by a form or control
event–or modify an existing function–follow these steps:

1 Open the form in the Form Designer.

2 Select the form itself or the control (or menu item) in question.

3 Open the C/AL editor (choose C/AL Code from the View menu).

4 In the editor, you will only have access to those triggers that are relevant for
the object that you selected. Enter C/AL code in those triggers you want to
use, or modify those existing triggers you want to.

160 Form and Control Triggers

Chapter 8. Extending the Functionality of Your Forms

5 You can test-compile the form, thus including the code, by choosing
Compile from the Tools menu.

If you are not familiar with the C/AL programming language, you should read
Part 5, Codeunits, in this guide.

Form and Control Triggers 161

Chapter 8. Extending the Functionality of Your Forms

162 Form and Control Triggers

Part 4
Reports
Chapter 9
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.

This chapter introduces the fundamental concepts

and basic tasks involved in designing reports.

· What Are Reports?

· What Happens When a Report Runs?
· The Report Designer
· Saving, Compiling and Running Reports
 Chapter 9. Report Fundamentals

9.1 What Are Reports?

Reports in C/SIDE have several purposes:

· Reports are used to print information from a database in a structured way.

For example, in a sales order application, you can create a report that
contains a list of all customers and for each customer lists all orders placed
by that customer.
· All documents pertaining to an application must be created as reports. For
example, in order to print an invoice, you will create a report that is
automatically filled out with the relevant information.
· Reports can be non-printing. While this may sound like a contradiction in
terms, it is not. A report can be used to automate many recurring tasks such
as updating all prices in an item list. This could be performed entirely from
C/AL code in a codeunit, but using a report makes it a lot easier because
you can use the powerful data modeling available for report design.
The following diagram shows the components of a report and their
relationship. This and the following chapters will explore all components in
depth.

Report Description
Properties
Triggers
Data Items
Properties
Triggers
Sections
Properties
Triggers
Controls
Properties

Request Form
Properties
Triggers
Controls
Properties
Triggers

166 What Are Reports?

 Chapter 9. Report Fundamentals

The Report Components

The diagram above outlines how a report is composed from a number of
different components. Below you will find a short description of each
component.

Report Description This is the total description of the report: how data is
collected, and how data is presented on paper when the report is run. The
report description is stored in the database.

Data Item A data item corresponds to a table. In order to retrieve information

from the tables in the database, you define data items. When a report uses
more than one table, you set relations between the data items in order to
retrieve and organize data in the way that you want.

Section In a printing report, each data item has one or more sections. A
section can be thought of as a block of information to print on the paper. The
complete report is composed of a number of sections, some that are printed
only once, for example a header, and some that are printed for each record that
is retrieved from the database.

Control The information that is 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
(but also complex calculations), labels for printing static text such as a caption
for a column of data, and shapes, images and picture boxes, for printing
graphical elements (lines, circles) and bitmap pictures in a report.

Request Form A request form is a form that is run before the actual report
begins execution. It is used to gather requests and options from the user of the
report–for example, sort order or level of detail.

Property A property is an attribute of an object–report, data item, section,

and so forth–that characterizes the object in some way: color, size, whether it
is displayed, and much else. Properties are set on the Property Sheet of an
object.

Trigger Certain predefined events that happen to a report cause the system
to execute a user-definable C/AL function–the event triggers the function. As
you can see in the diagram, the report itself, the data items, the sections, the
request form and the controls on the request form all have triggers. Triggers
are edited in the C/AL editor.

What Are Reports? 167

 Chapter 9. Report Fundamentals

Logical and Visual Design

There are two sides to designing a report: defining the logical structure, the
data model, and designing the visual layout.

Defining the data model means defining how the data for the report is
collected. This includes

· defining the tables the report will use by creating data items.
· defining relationships between data items if the report uses more than one
table.
· defining the key, sort order and filters to use with the involved data items.
· defining how data is to be grouped.
· defining how subtotals and totals are to be calculated.
· possibly writing C/AL code in data item triggers to obtain advanced
functionality.
Data Items The data model of a report is built from data items. A data item corresponds to
a table. When the report is run (see the diagram on page 171) each data item is
iterated for all records in the underlying table. When a report is based on more
than one table, you establish a hierarchy of data items to control how the
information is gathered by indenting data items.

Example

In order to make a report that prints out a list of customers and for each customer lists sales orders
placed by that customer, you will define two data items: one that corresponds to the Customer table
and one that corresponds to the Sales Order table. The second data item is indented: as the report
works its way through the records in the Customer table, for each customer all sales orders that are
related to this customer must be found by going through the records in the Sales Order table.

Sections The visual layout of a report includes the sections. In a printing report
(remember that reports do not have to print anything), one or more sections
are attached to each data item. There are several types of sections, each
having a specific function. Normally, the bulk of the data is printed out in the
body section of a data item, while the header section of the data item is used
to print information before any record of the data item is printed (for example,
column captions), but there are reports–like some of the examples in this
guide–where the body section is not used at all, and all information is printed
in other sections.

The picture below shows a finished report.

168 What Are Reports?

Chapter 9. Report Fundamentals

Sales Statistics
CRONUS International Inc.

Customer: No.: 10000..30000

09/28/95 10/28/95 11/28/95

No. Name ...before 10/27/95 11/27/95 12/27/95 after...

10000 Kontorforsyningen A/S

Sales (LCY) 57,509.00 0.00 0.00 0.00 0.00

Profit (LCY) 12,655.00 0.00 0.00 0.00 0.00

Profit % 22.0 0.0 0.0 0.0 0.0

Inv. Discounts (LCY) 0.00 0.00 0.00 0.00 0.00

Pmt. Discounts (LCY) 0.00 0.00 0.00 0.00 0.00

20000 Ravel Møbler

Sales (LCY) 1,525.00 0.00 0.00 0.00 0.00
Profit (LCY) 335.00 0.00 0.00 0.00 0.00

Profit % 22.0 0.0 0.0 0.0 0.0

Inv. Discounts (LCY) 0.00 0.00 0.00 0.00 0.00

Pmt. Discounts (LCY) 0.00 0.00 0.00 0.00 0.00

30000 Lauritzen Kontormøbler A/S

Sales (LCY) 13,676.20 0.00 0.00 0.00 0.00

Profit (LCY) 2,444.20 0.00 0.00 0.00 0.00

Profit % 17.9 0.0 0.0 0.0 0.0
Inv. Discounts (LCY) 0.00 0.00 0.00 0.00 0.00

Pmt. Discounts (LCY) 0.00 0.00 0.00 0.00 0.00

Total

Sales (LCY) 72,710.20 0.00 0.00 0.00 0.00

Profit (LCY) 15,434.20 0.00 0.00 0.00 0.00

Profit % 21.2 0.0 0.0 0.0 0.0

Inv. Discounts (LCY) 0.00 0.00 0.00 0.00 0.00

Pmt. Discounts (LCY) 0.00 0.00 0.00 0.00 0.00

The report above prints sales statistics information and retrieves all its data
from one table. It demonstrates a range of the features that are available for
designing reports

· Before any record from the table is printed, there is a header–containing a

title and information about the filter that was used on the customer
numbers.
· Each body section prints information about a customer on several lines. The
“Profit %” lines are calculated as the report is run.

What Are Reports? 169

Chapter 9. Report Fundamentals

· After all records (all records that were selected by the filter, that is) have
been printed, a footer section is printed that contains totals for the selected
customers.
· In the body section and in the footer section, a filter has been applied to
create columns where data are collected and totalled for different periods.

170 What Are Reports?

 Chapter 9. Report Fundamentals

9.2 What Happens When a Report Runs?

The two flow charts in this chapter are simplified versions of the flow charts in
Appendix F, Report Flow Charts, on page 363. If you want to acquaint yourself
with all details–including why and when triggers are executed–you should
consult that appendix. The focus here will be on describing in general terms
the way a report is run.

The Report Run

The flowchart below illustrates the events that take place when a report runs.

Entry point

Exit

Report.Run

Call Init Trigger

ReqForm.Run

Cancel

OK / Print / Preview

Call PreReport
Trigger

DataItem.Run

Get Next DataItem OK

No more

Call PostReport
Trigger

1 When the user initiates the report run, the OnInitReport trigger is called.
This trigger can perform processing that would be necessary before any part
of the report is run–or stop the report.

What Happens When a Report Runs? 171

Chapter 9. Report Fundamentals

2 If the OnInitReport does not end the processing of the report, the request
form for the report is run, if it is defined. Here, the user can choose to cancel
the report run.

3 If the user chooses to continue, the OnPreReport trigger is called. At this

point, no data has yet been processed.

4 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).

5 When the first data item has been processed, the next (if any) data item will
be processed in the same way.

6 When there are no more data items, the OnPostReport trigger is called. You
can use this trigger to do any post processing that is necessary, for example
cleaning up by removing temporary files.

172 What Happens When a Report Runs?

Chapter 9. Report Fundamentals

The flow chart below further explores step 4–how a data item is processed:

DataItem.Run

Header.Run

OK GroupHeader.Run

Call PreDataItem
Trigger

GetRecord Body.Run

No more

DataItem.Run
Call PostDataItem
Trigger Get next lower
OK
DataItem

No more

GroupFooter.Run

Footer.Run

1 Before the first record is retrieved, the OnPreDataItem trigger is called, and
after the last record has been processed, the OnPostDataItem trigger is
called.

What Happens When a Report Runs? 173

Chapter 9. Report Fundamentals

2 Between these two triggers, the records of the data item are processed.
Processing a record means executing the record triggers and outputting
sections. C/SIDE also determines whether the current record should cause
outputting of a special section: header, footer, group header or group
footer.

3 If there is an indented data item, a data item run will be initiated for this
data item (data items can be nested 10 levels deep).

4 When there are no more records to be processed in a data item, control

returns to the point from which the processing was initiated. For an
indented data item this will be to the next record of the data item on the
next higher level. If the data item is already on the highest level (indentation
is zero) control will return to the report–as shown in the first flow chart
(Report.Run).

174 What Happens When a Report Runs?

 Chapter 9. Report Fundamentals

9.3 The Report Designer

The Report Designer contains two additional designers: the Section Designer,
used for designing the layout of reports, and the Request Options Form
Designer, used for designing request options forms.

The Report Designer

In the Report Designer window you define the data model by adding data items
and indenting them appropriately:

Properties and triggers for each of the data items can be edited by opening the
Property Sheet or the C/AL editor, respectively, while the data item is selected.
Properties and triggers for the report can be edited by selecting an empty line
in the Report Designer window and then opening the Property Sheet or the
C/AL editor, or by choosing Select Object from the Edit menu.

The Section Designer

When one or more data items have been defined, you can design the visual
layout of the report in the Section Designer.

The Report Designer 175

Chapter 9. Report Fundamentals

You can use the Field Menu–similar to the Field Menu in the Form Designer–to
select fields and place them in the sections as controls. In the picture below, a
number of text boxes and labels have been placed in four sections.

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 typically will be printed several times as the report loop is
iterated. You can control whether the header will be printed when a page break
occurs while body sections of the same data item are being printed.

You can edit properties and triggers for each section by opening the Property
Sheet 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 (as not all properties are relevant on a report), and you
can use the same tools to modify the properties (the Font Tool, the Color Tool).
You can see a list of the properties on the Property Sheet, and you can read
about them in chapter 7, Designing Forms, or in the online C/SIDE Reference
Guide.

176 The Report Designer

 Chapter 9. Report Fundamentals

The Request Options Form Designer

The Request Options Form Designer is used to create a form with fields that
prompt the user for options before the report is run. This designer works
exactly like the Form Designer.

You only have to use this designer if you want to prompt the user to select
options. When a report is run, the request form looks like this:

As you can see, a form with a tab control has been created. The first two tabs
correspond to data items. They are created automatically (though you can
control the contents by setting properties of the data items), and they are used
for setting filters and defining the sort order.

The third tab, Options, only appears when the Request Options Form Designer
has been used to create a request options form.

The Report Designer 177

Chapter 9. Report Fundamentals

The form has the same properties and triggers as any other form, and the same
controls can be placed on it.

178 The Report Designer

 Chapter 9. Report Fundamentals

9.4 Saving, Compiling and Running Reports

After you have designed a report, you must save and compile it before it can be
run. Normally, you will do this when you are done designing the report.
However, you may want to save a report that is not yet finished and thus
cannot be compiled, for example if the report is more complex than the reports
described so far and contains C/AL code. You can also test-compile a report
without closing or saving it.

Saving and Closing a Report

A report is closed when the Report Designer window is closed. You can close
this window in the same ways that you can close any other window.

To save a report:

1 When you close a report, C/SIDE will ask whether the report should be
saved. If it is a new report (a report that has not been saved before) you will
have to assign an ID and a name. The ID must be unique and follow the rules
for numbering objects–your C/SIDE dealer will provide you with this
information.

Hint: if you enter ID and Name as report properties, these values will be
used, and you will not be prompted for ID and Name when you close the
report.

2 The option field Compiled is by default set to TRUE (displayed as a check

mark). If your report is not yet ready to be compiled, remove the check mark
by clicking in the field.

3 Choose OK to save the report.

Saving, Compiling and Running Reports 179

 Chapter 9. Report Fundamentals

You can save a report without closing it by choosing Save or Save As from the
File menu. By using Save As, you can rename an existing report–thereby in
effect copying it.

Compiling a Report
Reports, like other objects in C/SIDE, must be compiled before they can be run.
As described above, you can choose to compile a report whenever you are
saving it.

While you are designing a report, you may want to test-compile a report, to find
possible errors (this possibility will be more important if the report contains
C/AL code in triggers, as described in chapter 11). You can test-compile a report
during design by choosing the Compile option from the Tools menu.

Running a Report
In a finished application your reports will be incorporated into menus, or they
will be called from, for example, a command button on a form. However, while
you are designing reports, you will often want to run them before they have
been integrated into an application.

Test-running reports While designing a report, you can test-run the report by choosing Run from the
File menu. In this way, the report will be compiled and run in its current stage
of development. It will not be saved, which means that you can use this
function to verify that the changes you are making work as intended before you
save them.

Running reports from You can run a report from the list of reports in the Object Designer main
the Object Designer window by selecting it and clicking the Run button.

180 Saving, Compiling and Running Reports

Chapter 9. Report Fundamentals

Saving, Compiling and Running Reports 181

Chapter 9. Report Fundamentals

182 Saving, Compiling and Running Reports

Chapter 10
Designing Reports

This chapter describes the properties of reports,

and then, by creating two examples, shows the
basic steps involved in designing reports.

· Report Properties
· Designing a SImple Report
· Designing a More Advanced Report
 Chapter 10. Designing Reports

10.1 Report Properties

As described in Chapter 1, C/SIDE Fundamentals, properties are a system-wide
feature and every application object has some properties. All objects in a
report have properties:

· The report itself

· The data items
· The sections
· The controls in the section
· The request form
· The controls on the request form
Properties for reports can be set by opening the Property Sheet (choose
Properties from the View menu) while an object is selected.

You select objects as follows:

· Select a data item in the Report Designer window by clicking it.

· Select the report itself by clicking an empty line or by choosing Select Object
from the Edit menu.
· Select a section in the Section Designer by clicking either the section bar or
somewhere in the section (not on a control, though).
· Select a control by clicking it.
Set the value of a property in the Value field of the property on the Property
Sheet. As soon as you leave this field (by hitting Enter or by moving with the
arrow keys), the property will be updated. If what you entered contains an
error, the update will not be accepted.

184 Report Properties

 Chapter 10. Designing Reports

Default values are displayed in angle brackets (<>). You can reset any
property (for which there is a default) to the default by deleting the current
value and then moving out of the field.

How Properties Are Inherited

Controls that have a direct relationship to table fields will inherit the settings of
those properties that are common to the field and the control. For example, in
an accounting application you will want to store some calculated amounts with
five decimal places, to obtain a high degree of precision. However, on a printed
report, you will only want to display currency amounts with the customary
number of decimal places. You can then change the DecimalPlaces property of
the text box control to display fewer decimals than the default (but not more,
obviously).

Report Properties
The table below briefly describes the report properties. All properties are
described in detail in the online C/SIDE Reference Guide. You can get context-
sensitive Help for a property by opening the Property Sheet for a report,
placing the cursor on a property and pressing F1.

The Property Sheet for a report is opened by choosing Properties from the View
menu while an empty line is selected in the Report Designer window, or by
choosing Select Object from the Edit menu.

Property Meaning
ID ID of the report–must be unique among reports.
Name Name.
Caption Caption (shown on request form window, for example–default is Name).
ShowPrintStatus Should the printing status window be displayed during printing (with the
opportunity to cancel printing)?
UseReqForm Should the request form be run before the report is run?
UseSystemPrinter If Yes, then the system default printer is suggested as printer for the report. If
No, then the printer defined for the combination User/Report in the setup of
the system is suggested.
ProcessingOnly No printing–only processing. If Yes, the report cannot have sections.
Description Description–for internal purposes, as it is not user-visible.
TopMargin Topmargin in 1/100 mm.
BottomMargin Bottom margin in 1/100 mm.
LeftMargin Left margin in 1/100 mm.

Report Properties 185

 Chapter 10. Designing Reports

Property Meaning
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 that retrieve information from tables that he or she cannot
normally access.)

Data Item Properties

The table below briefly describes the data item properties. All properties are
described in detail in the online C/SIDE Reference Guide. You can get context-
sensitive Help for a property by opening the Property Sheet for a Data Item,
placing the cursor on a property and pressing F1.

Property Meaning
DataItemIndent Indentation level (can be set in the designer when creating data
items).
DataItemTable Table of item (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 DataItem
will be linked to.
DataItemLink Link between the current Data Item and the Data Item specified by
DataItemLinkReference.
NewPagePerGroup Should each group be printed on a separate page?
NewPagePerRecord Should each record be printed on a separate page?
ReqFilterHeading Tab caption for this item on request form (default is name of
DataItemTable).
ReqFilterFields Names of the fields that will be included in the ReqFilter form.
TotalFields Names of the fields for which totals will be calculated.
GroupTotalFields Names of the fields that will be used for grouping data.
CalcFields Names 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 variable (default is name of DataItemTable).
PrintOnlyIfDetail Print item only if sublevels generate output.

186 Report Properties

 Chapter 10. Designing Reports

Section Properties
The table below briefly describes the section properties. All properties are
described in detail in the online C/SIDE Reference Guide. You can get context-
sensitive Help for a property by opening the Property Sheet for a Section,
placing the cursor on a property and pressing F1.

Property Meaning
PrintOnEveryPage Should header and footers be printed on all pages?
PlaceInBottom Should footer be placed below last line or at bottom of page?
SectionWidth Width in 1/100 mm.
SectionHeight Height in 1/100 mm.

Control Properties
Controls in reports have exactly the same properties as controls on forms–that
is, those properties that it makes sense to set in a report. The Property Sheet of
a control shows the properties, and chapter 7, Designing Forms, describes
each property, as does the online C/SIDE Reference Guide.

Report Properties 187

 Chapter 10. Designing Reports

10.2 Designing a Simple Report

This section goes through the steps required to create a very simple report, in
which a list of customers is created, based on one table that contains customer
information.

Defining the Data Model

The first step is to define the data model by creating the data items that you
want to use.

To create a data item:

1 From the Tools menu, choose the Object Designer.

2 In the Object Designer, click the Report button.

3 Click the New button.

4 C/SIDE opens the Report Designer. Select the first data item field (by
clicking it), and choose a table from the lookup form that you open by
clicking the p button. The Name is by default set to the name of the table.
You do not have to change it in this report. In the example here, the
Customer table has been chosen, and the default for Name is “Customer”.

188 Designing a Simple Report

Chapter 10. Designing Reports

5 Open the Property Sheet for the data item by choosing Properties from the
View menu.

6 Select the DataItemTableView property and click the assist-edit button (k)
to open this window:

7 Choose the key, sort order and filters that you want to use. In the example
here, a key (previously defined during table design) consisting only of the
No. field has been chosen, and the sort order is set to Ascending. The Table
Filter field has been left empty, meaning that a permanent filter is not
defined on the table. After you enter your choices, press OK.

8 Select the ReqFilterFields property, and click the assist-edit button (k) to
open this window:

Designing a Simple Report 189

Chapter 10. Designing Reports

9 Select the fields on which the user will often need to set filters–you can use
the lookup function to select them. In the example here, the fields No. and
Country Code have been selected. When you have selected the fields, press
OK.

The picture below shows the request form the user will see when the report is
run (with the various choices made as in the steps above).

As the key and sort order were established during report design, the only
choice left for the user involves setting filters. The fields that were defined as
ReqFilterFields are shown, but the user can also choose to put a filter on other
fields by adding lines below those that are already used.

Concerning ReqFilterFields, you should be aware that the user can choose to
set filters on other fields than those you specify. However, it will still be a good
idea to add the fields that those who use the report will often want to set filters
on. If the table has a lot of fields, the casual user may find it difficult to find the
relevant fields to filter from a lookup list of all the fields in the table.

You can remove the filter-selection tab altogether by not defining any
ReqFilterFields for the data item and by setting 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 will be displayed. On this,

the user can choose Print, Cancel, and so forth. Finally, if you set UseReqForm
to No, the report will start printing as soon as it is run. In this case, the user will
not be able to change his or her mind and cancel the report run altogether. (It
will still be possible to cancel printing, but some pages will probably be
printed).

190 Designing a Simple Report

Chapter 10. Designing Reports

If a DataItemTableView is not defined, the user will be able to select key and
sort order at runtime. Then, the request form will look like this:

When the Sort... button is pushed, the user can choose the key and sort order
from this form:

Be careful...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
about what you allow the user to change. In a more complex report, where you
work with data from several tables, the functionality may well depend on a
specific key and sort order. On the other hand, letting the user choose filters
freely will not interfere with the logic of the report. In a very simple report like
this one, you can select a key and define a sort order if you want, or leave it up
to user.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Designing a Simple Report 191

 Chapter 10. Designing Reports

Designing the Sections

So far, only the data model of the report has been defined. So far, nothing will
be printed. The next step, therefore, is to design the sections.

To design report sections:

1 Open the Section Designer by choosing Sections from the View menu while
the Report Designer window has the focus. Having created a data item as
described above, the Section Designer will look like this:

As you can see, a section named “Customer - Body” (‘1’ means that this is
presently the first section of this data item) has been inserted. By default, a
Body section will be inserted for each data item that has been created; these
sections will be in the same order as the data items in the Report Designer.

2 Now, insert a header section for the Customer data item. Choose Insert New
from the Edit menu. The following form will appear:

192 Designing a Simple Report

Chapter 10. Designing Reports

3 Choose Header as the Section Type and Before Current Section. Then press
OK. The Section Designer now looks like this:

4 Open the field menu by choosing Field Menu from the View menu. Select the
fields that you want in the report. (You can select multiple fields by holding
down Ctrl while clicking in the selection bar.) In the example below, four
fields have been selected.

Designing a Simple Report 193

Chapter 10. Designing Reports

5 Move the mouse 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 at the left side of the section and click again. A text box with
an attached label will be inserted for each selected field.

6 Open the Property Sheet by choosing Properties from the View menu. Click
in the Header section. Look at the setting of SectionWidth (the unit of
measure is 1/100 mm).

194 Designing a Simple Report

Chapter 10. Designing Reports

All sections widths have been modified to make room for the inserted controls
(the default width, when no controls have been inserted, is 12000). In this
case, the resulting width is 15450, or 15.45 cm. If the report is going to be
printed on A4 paper this is perfectly acceptable–that paper is 21 cm wide.

7 Select all the labels as a multiple selection (hold down Ctrl while clicking),
and move them all into the Header section in one move (in this way, the
alignment of labels and text boxes will be preserved).

Now, the report is ready to be printed, but it still needs some work before it will
look good on paper.

8 If the report, when it is run, ends up consisting of more than one page, you
will want the Header section–containing the labels–to appear on every
page. Open the Property Sheet for the Header section and set the
PrintOnEveryPage property to Yes (see the picture in step 6 above).

Designing a Simple Report 195

Chapter 10. Designing Reports

9 Moving the labels out of the Body section has left this section too
high–there will be an empty line for each customer record that is printed. To
resize the Body section, move the mouse cursor into the 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 Save and close the report, and run it from the Object Designer. The example
described so far gives this result with sample data:

No. Name Address Phone No.

10000 Kontorforsyningen A/S Carl Blochs Gade 7 11223344

20000 Ravel Møbler Parkvej 44 22334455

30000 Lauritzen Kontormøbler A/S Jomfru Ane Gade 56 33445566
01121212 Spotsmeyer's Furnishings 612 South Sunset Drive 9998887771
01445544 Progressive Home Furnishings 3000 Roosevelt Blvd. 8887776661

01454545 New Concepts Furniture 705 West Peachtree Street 7776665551

As you can see, the label and the data in No. do not line up very nicely. This is
because both controls have their alignment set to General (the default). The
label is left-aligned because it contains text, while the text boxes are right-
aligned because they contain numbers.

A simple solution is to right-align the label.

11 Select the No. label and open the Property Sheet. Set the HorzAlign
property to Right.

Now the report looks like this:

No. Name Address Phone No.

10000 Kontorforsyningen A/S Carl Blochs Gade 7 11223344

20000 Ravel Møbler Parkvej 44 22334455

30000 Lauritzen Kontormøbler A/S Jomfru Ane Gade 56 33445566
01121212 Spotsmeyer's Furnishings 612 South Sunset Drive 9998887771
01445544 Progressive Home Furnishings 3000 Roosevelt Blvd. 8887776661

01454545 New Concepts Furniture 705 West Peachtree Street 7776665551

196 Designing a Simple Report

 Chapter 10. Designing Reports

10.3 Designing a More Advanced Report

The report designed in section 10.2 was very simple: it ran through one table
and printed out the records. In this section, you will learn to design reports that
use more than one table.

The sample report that will be created uses two tables: one is the customer
table, as in the preceding example. The other table contains sales lines, lines
from not-yet-posted sales orders that contain information about the actual
items that have been ordered. There is a one-to-many relationship between
the two tables: while one customer can have many items on order, a sales line
can pertain to only one customer.

Defining the Data Model

The description of the steps involved in creating this report presumes that you
are familiar with the techniques explained in section 10.2 above.

To define the data model:

1 In the Report Designer window, choose the Customer table as the first data
item, and the Sales Line table as the second.

2 Indent the Sales Line data item by clicking the right-arrow button once while
the data item is selected:
.

The data model defined thus far will work like this:

· The report will run through the Customer data item.

Designing a More Advanced Report 197

Chapter 10. Designing Reports

· For each record in the Customer data item, the report will run through the
entire Sales Line data item.
This is clearly not the purpose of the report–you need a way to select only
those Sales Line records that are related to the current customer. This is
accomplished by the DataItemLink and DataItemLinkReference properties. The
DataItemLinkReference property points to a data item on a higher level (with
less indentation) and the DataItemLink property specifies a field in each data
item: here, records will be selected from the Sales Line table only when the
Sell-to Customer No. is the same as the No. in the Customer table.

3 Open the Property Sheet for the Sales Line data item.

4 Set the DataItemLinkReference property to the name of the less-indented

data item (Customer) that the more-indented data item (Sales Line) must be
related to. In most cases, including this one, this is the default.
.

5 In the value field of the DataItemLink property, open the form shown below
by clicking the k button.

198 Designing a More Advanced Report

 Chapter 10. Designing Reports

6 In the Field field, enter the name of the field from Sales LIne (the more-
indented data item) that must correspond to a field from Customer (the
less-indented data item). You can use the lookup function to select the field.

7 In the Reference Field field, enter the name of the field from Customer that
must correspond to the field from Sales Line. Again, you can use the lookup
function to select the field. In the example below, the Sell-to Customer No.
field from the Sales Line data item and the No. field from the Customer data
item have been chosen.

8 Finally, open the Property Sheet for the Customer data item, and set the
PrintOnlyIfDetail property to Yes. This will cause the Customer body
sections to be printed only if there is data to print from Sales Line.

The data model now works like this:

· The Customer data item will be run through.

· For each record in the Customer data item, records in the Sales Line data
item will be selected 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 will be
printed–not even the information from the Customer data item.

Designing The Sections

Presuming that you already know how to design the sections for a report with
just one data item, the description here concentrates on showing how to
handle a situation with two data item.

Designing a More Advanced Report 199

Chapter 10. Designing Reports

To design the sections:

1 When you first open the Section Designer, there will already be a Body
section for each data item. Add a Header section for the Customer data
item.

2 Add fields to the Customer body section. Move the labels up into the Header
section.

So far, the procedure has been exactly the same as for creating the first, simple
report. Now, continue like this

3 Add fields to the Sales Line body section.

4 At this point, you need to make a decision about the labels for the controls
of Sales Line: if they stay where they are right now, they will be printed for
each record of the data item. If a header section is added for Sales Line, this
header section will be printed each time the data item loop is entered,
which is for each record of the Customer data item. As neither of these
solutions seems very good, you can take a third approach: you can move
the labels into the header section of the Customer data item, like this:

200 Designing a More Advanced Report

Chapter 10. Designing Reports

5 Now, labels for both the Customer records and the Sales Line records will be
printed as column captions in the Customer Header section (remember to
set the PrintOnEveryPage property of this section to Yes). In order to make
the connection between labels and data clear, the labels for the Sales Line
columns can be changed to the normal font weight instead of the default
bold. Also, the text boxes of the Customer data item can be changed to bold,
to make these records stand out among the lines that are printed. (There
are bound to be a lot more records from Sales Line than from Customer.)
Furthermore, the Sales Line labels have been resized to occupy only one
line, and an empty line has been added to the header section.

6 Save and close the report, and run it from the Object Designer. The example
described gives this result with sample data:

Designing a More Advanced Report 201

Chapter 10. Designing Reports

No. Name Address Phone No.

Document No. Date Description Quantity Unit Price Amount

10000 Kontorforsyningen A/S Carl Blochs Gade 7 11223344

941016 05/11/95 ANTWERP Conference Table 1 3,599.00 3,599.00
20000 Ravel Møbler Parkvej 44 22334455

941017 05/11/95 ST.MORITZ Storage Unit/Drawers 2 2,929.00 5,272.20

941017 05/11/95 INNSBRUCK Storage Unit/G.Door 1 2,500.00 2,250.00

941017 05/11/95 INNSBRUCK Storage Unit/W.Door 1 2,193.00 1,973.70

30000 Lauritzen Kontormøbler A/S Jomfru Ane Gade 56 33445566

941023 02/01/95 ANTWERP Conference Table 4 3,599.00 13,676.20

941023 02/01/95 BERLIN Guest Chair, yellow 23 1,265.00 20,366.50

202 Designing a More Advanced Report

Chapter 11
Extending the Functionality of Your
Reports

This chapter describes how to group and total

data when creating reports in C/SIDE. It also gives
an overview of the report triggers and, finally,
uses some of the advanced facilities of the Report
Designer.

· Grouping and Totaling

· Report Triggers
· Advanced Sample Reports
 Chapter 11. Extending the Functionality of Your Reports

11.1 Grouping and Totaling

Grouping and totaling data are crucial to creating useful reports. By grouping
and totaling data your reports can provide information that is not otherwise
readily available.

The second report created in chapter 10 listed customers and those entries
from the Sales Line table that pertained to each customer. You can use
grouping and totaling to enhance this information in several ways.

First of all, if the report is to provide statistical information, it will be more

useful to have the sales lines grouped according to the items (grouping on the
item number, which identifies each item) instead of printing all lines from all
sales documents. Each line should then provide figures for the total quantity
and the total amount for each item per customer.

Second, it would be useful to have a total amount per customer, showing how
much this customer has on order all in all.

This is the report that will created below.

Defining the Data Model

The first steps in creating this report involve designing a report similar to the
report created in Designing a More Advanced Report on page 197.

To add the grouping and totaling, follow these steps:

1 In the Property Sheet of Sales Line (the indented data item), enter as the
value of the GroupTotalField property, the name of the field you want to be
used for grouping the records. You can use the assist-edit button to help
you select the field. Here, the No. field is used:

204 Grouping and Totaling

Chapter 11. Extending the Functionality of Your Reports

2 Use the assist-edit button for the DataItemTableView property, and then
select a key. You have to select a key that contains the field you want to
group by.

3 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 fields change. In other words: you may have to create a distinct key
for reports that access data in ways other those used by than your
application in general. For this report, a secondary key, consisting of the No.
field only, was created for the Sales Line table:

4 Enter the names of those fields for which totals should be calculated as the
value of the TotalFields property. You can use the assist-edit button to help
you select the fields. Here, the fields named Quantity and Amount are
selected:

This data model is now defined. This is what has been accomplished:

· For each record in the Customer data item, those records in the Sales Line
data item that are related to this customer are selected.

Grouping and Totaling 205

 Chapter 11. Extending the Functionality of Your Reports

· The records from the Sales Line data item are grouped according to the item
number.
· Totals are maintained for the Quantity and Amount fields of the Sales Line
data item.

The Relationship between Totals and Sections

In the report being designed, a hierarchy of data items have been established,
where Customer is the highest level data item and Sales Line is an indented
data item. Further, the records of Sales Line will be grouped on the No. field,
and totals will be calculated for the Amount and Quantity fields.

What, then, is the relationship between these totals and the sections–that is,
how can these totals be printed?

Until now, only Header and Body sections have been used. To print totals, you
will need to use some new sections. The table below gives an overview of all
types of sections:

Section Name Output

Header Before a data item loop begins and (if the PrintOnEveryPage property of the
section is Yes) also on each new page.
Body 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 After the loop has finished, and (if the PrintOnEveryPage property of the
section is Yes), also on each new page. Moreover, if the PlaceInBottom
property of the section is 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 A page break occurs during a data item loop. Printed on top of the new page.
This section is printed after a possible Header section of the data item.
TransportFooter A page break occurs during a data item loop. Printed before the page break,
This section is printed before a possible Footer section of the data item.

In order to print out the totals, you will need to use both a GroupFooter and a
Footer section for the Sales Line (indented) data item.

In the GroupFooter section, the totals for Quantity and Amount will be for the
defined group–remember that the No. field was used for grouping.

206 Grouping and Totaling

 Chapter 11. Extending the Functionality of Your Reports

When the entire data item has been iterated, the grand total can be printed in
the Footer section of the Sales Line data item.

The flow in this example can be summarized as follows:

1 For each record of the Customer data item, a loop for the Sales Line data
item is begun.

2 Whenever the contents of the No. field change, the GroupFooter is

outputted.

3 When the Sales Line loop ends, the Footer will be outputted. As the Body
section of the Customer data item was printed before any section of the
indented data item, the Footer is also the last section that will be printed.
Therefore, this section can be used to print summary information about the
customers.

That is, the Quantity and Amount totals for each item that a specific customer
has on order will be placed in a GroupFooter section of the Sales Line data
item, while the grand total for the Amount that the customer has on order will
be placed in a Footer section of the Sales Line data item (a Quantity total is
also maintained, of course, but this information is not too useful, since it will
be a total of quantities for all kinds of different items.)

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
properties of sections, such as PrintInBottom and PrintOnEveryPage, apply to
an entire data item. This means that you cannot, for example, have two Footers
for a data item, one for the ‘normal’ pages and one for the last page.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Designing the Sections

As usual, when you open the Section Designer, a Body section for each defined
data item has been inserted.

To design the sections:

1 Add a Header section for the Customer data item. This section will be used
to print headings for the columns in the report.

2 Add a GroupFooter section for the Sales Line data item. This section will be
used to print the summary information about each item.

Grouping and Totaling 207

Chapter 11. Extending the Functionality of Your Reports

3 Add a Footer section for the Sales Line data item. This section will be used
to print the summary information about each customer.

In this report, nothing will be printed in the Body section of the Sales Line data
item. Therefore, this section should be deleted. (You delete a section by
clicking on the section bar, then choosing Delete from the Edit menu. You will
be prompted to confirm the deletion.) The Section Designer will now look like
this:

4 Select the Body section of the Customer data item (by clicking the section
bar). Then open the field menu by choosing Field Menu from the View menu.

5 Select fields from the field menu. Here, four fields have been selected:

6 Click once in the Section Designer window to activate the window, then
move the cursor into the Body section of the Customer data item. Click to
insert text boxes and labels for the four selected fields.

208 Grouping and Totaling

Chapter 11. Extending the Functionality of Your Reports

7 Move the labels up into the Header section of the Customer data item and
adjust the vertical size of the Body section. Resize the labels vertically and
move them up to the top of the Header section. The Section Designer now
looks like this:

8 Select the GroupFooter section of the Sales Line data item (by clicking the
section bar) and open the field menu by choosing Field Menu from the View
menu.

9 Select fields from the field menu. Here, the No., Description, Quantity and
Amount fields have been selected. Insert the fields in the GroupFooter
section of the Sales Line data item. Delete the labels, and resize the section
vertically.

10 Select the Footer section of the Sales Line data item. Insert the Amount field
here and remove the label. Let the section have its default size–this way,
there will be some empty space before each new customer.

Grouping and Totaling 209

Chapter 11. Extending the Functionality of Your Reports

11 Save, close and run the report.

So far, the report will look like this when printed:

No. Name Address Phone No.

10000 Kontorforsyningen A/S Carl Blochs Gade 7 11223344

1920-S ANTWERP Conference Table 9 32,391.00

32,391.00

20000 Ravel Møbler Parkvej 44 22334455

1928-W ST.MORITZ Storage Unit/Drawers 2 5,272.20

1964-W INNSBRUCK Storage Unit/G.Door 1 2,250.00

1976-W INNSBRUCK Storage Unit/W.Door 1 1,973.70

9,495.90

30000 Lauritzen Kontormøbler A/S Jomfru Ane Gade 56 33445566

1920-S ANTWERP Conference Table 4 13,676.20

1936-S BERLIN Guest Chair, yellow 23 20,366.50

34,042.70

Obviously, this report needs some work before it looks good and is truly
functional. For example, we need to devise a way to place captions for the
columns from the indented data item. But the logic works: for each customer,
there is a list of items where quantities and amounts have been summarized,
and the total amount for each customer is also calculated.

210 Grouping and Totaling

Chapter 11. Extending the Functionality of Your Reports

One desirable improvement is to add a line at the end of the report where the
grand total for all customers is printed. To do this, however, it is necessary to
use C/AL code in a report trigger. The Advanced Sample Reports section on
page 214 gives examples of how to do it.

Grouping and Totaling 211

 Chapter 11. Extending the Functionality of Your Reports

11.2 Triggers in Reports

While the system interprets and acts upon many events in a predefined way,
certain actions cause the system to execute a user-definable C/AL function
(the event triggers the function). In reports, triggers are typically used to
perform calculations and to control whether or not to output sections
(depending, for example, on the value in a field, or a choice the user made in
the request form). Perhaps the most important point about triggers, however,
is that using them allows you to control how data is selected and retrieved in a
more complex ways than using properties would.

Report Triggers
These triggers pertain to the report itself.

Trigger Executed
OnInitReport When the report is loaded.
OnPreReport –
Before the report is run but after the RequestForm has been run.
OnPostReport –
After the report has run but not if the report was stopped manually or by the
Break function.
The table only sketches out the main purpose of each trigger. Refer to the
online C/SIDE Reference Guide for concise descriptions and details.

Data Item Triggers

The following triggers pertain to each data item of the report:

Trigger Executed
OnPreDataItem Before the data item is processed, but after the associated variable has been
initialized.
OnAfterGetRecord When a record has been retrieved from the table.
OnPostDataItem When the data item has been iterated for the last time.
The table only sketches out the main purpose of each trigger. Refer to the
online C/SIDE Reference Guide for concise descriptions and details.

Section Triggers
These triggers pertain to each of the sections of a data item:

212 Triggers in Reports

Chapter 11. Extending the Functionality of Your Reports

Trigger Executed
OnPreSection Before processing a section.
OnPostSection After processing a section but before printing it.
The table only sketches out the main purpose of each trigger. Refer to the
online C/SIDE Reference Guide for concise descriptions and details.

Triggers in Reports 213

 Chapter 11. Extending the Functionality of Your Reports

11.3 Advanced Sample Reports

This final section will give examples of reports that are slightly more advanced
than those previously described. The examples are not intended to be
complete or ready to run, but are meant to give some ideas that you can use
when designing reports.

Using Virtual Tables

C/SIDE includes a number of virtual tables, such as the Integer table and the
Date table. They are described in chapter 5, Special C/SIDE Tables. This
section will show you how to use one of these tables, the Date table, in a
report.

Using the Date Table

The Date table consists of three fields, Period Type, Period Start and Period
End. Period Type can be Date, Week, Month, and so forth, while 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.)

The Date table will be used to create a report that writes out information from
the Cust. Ledger Entry table (the Customer Ledger Entry table, but the word
Customer has been abbreviated). For each day in a range of dates (that can be
chosen by the user), the report summarizes entries made on that date. For
each type of document (Invoice, Payment, and so forth), a line will be printed
containing the number of documents of this type and the sum of the amounts
of these lines. After each date, the total number of entries made on that day,
along with the total amount of all these entries, will be printed. Finally, the
total number of entries and the total amount for the selected date range will be
printed at the end of the report.

You could create the report by grouping 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 desirable, because it
would slow down all other transactions involving this table–in fact, all entries
concerning sales would be affected.

Defining the Data Model

There are two data items in this data model: one that is related to the Date
table and one that is related to the Cust. Ledger Entry table.

214 Advanced Sample Reports

Chapter 11. Extending the Functionality of Your Reports

To define the data model:

1 Open the Report Designer and create two data items with the Date and the
Cust. Ledger Entry as the underlying tables. Indent the Customer Ledger
Entry data item.

2 Open the Property Sheet for the Date data item. Then use the assist-edit
button to help you set the value of the DataItemTableView property so that
it selects records whose Period Type is Date. This is an important step, as
the iteration of the Date data item would otherwise run through all records,
including those for Weeks, Quarters, Months and Years.
r

3 Enter the Period Start field as the ReqFilterFields property of the Date data
item in order to let the user select a range of dates at run time.

Advanced Sample Reports 215

Chapter 11. Extending the Functionality of Your Reports

4 Open the Property Sheet for the Cust. Ledger Entry data item. Then use the
assist-edit button to help you set the value of the DataItemTableView
property to an appropriate key. An appropriate key in this case is a key
containing the Document Type field, as the definition of a group will be
based on this field. Here, a key is selected that has this field as its first
component. As the report is going to show only summarized information,
rather than all the entries, the other fields that are included in the key are
not significant. (No individual entries will be printed, so they do not need to
be sorted in any specific order.)

5 In the Property Sheet for the Cust. Ledger Entry data item, set the
DataItemLinkReference property to point to the Date data item (this is the
default). Then use the assist-edit button of the DataItemLink property to
specify the field that establishes the link between the two data items.
Choose the Date field from the Cust. Ledger Entry data item, and the Period
Start field from the Date data item.

216 Advanced Sample Reports

Chapter 11. Extending the Functionality of Your Reports

6 Enter the Document Type field as the value of the GroupTotalFields property
of the Cust. Ledger Entry data item, and enter the Amount field as the value
of the TotalFields property.

Thus far, the report will work like this:

· The user can select a range of dates from the request form of the report.
· The report will run through the Date table, with a constant filter on the
Period Type field that selects only records whose type is Date. If the user
selected a range, only dates in the range will be selected; otherwise all
dates will be used.
· For each selected date, records in the Cust. Ledger Entry data item that were
posted on that date will be selected.
· The records of the Cust. Ledger Entry data item will be grouped according to
the value of the Document Type field, and totals will be maintained for the
Amount field.

Advanced Sample Reports 217

 Chapter 11. Extending the Functionality of Your Reports

Designing the Sections

The design of the sections is fairly straightforward. The final screen looks like
this:

The sections contain some controls that do not have fields from the data items
as source expressions (Qty, TotalQty, TotalAmount and DateFilter). The
purpose of these controls will be explained below.

Otherwise, the design of the sections is as follows:

· There is a Header section for the Date data item, containing captions for the
columns of data in the report.
· There is a Footer section for the Date data item, used for printing totals for
all printed records.
· There are two GroupFooter sections for the Cust. Ledger Entry data item,
one with a text box for the Date field, one without. The reason for this
construction–and how to use it–will be explained below. Both sections will
print summarized information about the groups of this data item (remember
that the Document Type field was used for grouping here).
· There is a Footer section for the Cust. Ledger Entry data item, used for
printing totals.
Neither data item has a Body section.

Refining the Design by Using Triggers

In order to make this report work as desired, we will need to write a small
amount of C/AL code in triggers and to define a few variables. The report still
needs four things to make it work the way we want:

218 Advanced Sample Reports

Chapter 11. Extending the Functionality of Your Reports

1 The number of entries must be counted for each document type, for each
date and for the complete range of dates in the report.

2 The total amount for all entries in the report must be calculated.

3 The date for a group of entries (with different document types) should be
printed only once, when the first record in the group is printed.

4 At the end of the report, when the total number of entries and the total
amount are printed, the date range that was selected by the user should be
printed.

Counting the Number of Entries

The records in the Cust. Ledger Entry data item contain an amount–which is
totaled by using properties, as described in step 6 on page 217. The number of
entries cannot be calculated in the same way, as no field in the data item
record contains this information.

However, each record corresponds to exactly one entry. This means that the
number of entries can be counted by simply counting the records. It can be
done in this way

1 Create a global variable (here it is called Qty) of type Decimal.

2 Add the following C/AL code to the triggers of the Cust. Ledger Entry data
item:

Advanced Sample Reports 219

Chapter 11. Extending the Functionality of Your Reports

The statement in the OnPreDataItem trigger causes totals to be maintained for

the Qty variable in the same way as when you use the TotalFields property to
specify that totals will be maintained for a field in a record. The statement in
the OnAfterGetRecord trigger simply assigns a value of one to the Qty variable
each time a record is retrieved.

The CREATETOTALS function will 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 will contain the sum of all entries
with the same document type each time the Cust. Ledger Entry GroupFooter
section is printed. When the Footer section is printed, Qty will contain the sum
of all entries (that were selected–that is to say: all entries that pertain to the
same date).

The argument of the CREATETOTALS function must be of the Decimal type

(because the function will usually be used to sum amounts). Therefore, the Qty
variable was declared to be of Decimal type rather than Integer (which perhaps
would have been the intuitive choice). This means that the Qty text boxes in
the sections have to be formatted not to show any decimal places, as they by
default will have the format <2:2> when the SourceExpr is of the Decimal data
type.

Calculating the Total Amount and the Total Quantity

You want to print the total amount for all selected records from the Cust.
Ledger Entry data item at the end of the report, in the Footer section of the
Date data item. The value you want to print is, of course, the sum of all the
amounts that are printed in the report–but these amounts come from the Cust.
Ledger Entry data item, not the Date data item. This means that you cannot use
the TotalFields property to do the totaling.

220 Advanced Sample Reports

Chapter 11. Extending the Functionality of Your Reports

Correspondingly, the total number of posted entries should be printed in the

Footer section of the Date data item.

The solution is simple:

1 Declare two global variables: TotalAmount and TotalQty (refer to the picture
on page 219).

2 Add these lines to the OnAfterGetRecord trigger of the Cust. Ledger Entry
data item:

TotalQty := TotalQty + 1;
TotalAmount := TotalAmount + Amount;

The first line simply adds one to the TotalQty variable whenever a record is
retrieved, while the second line adds the retrieved Amount to the TotalAmount.
When the Date data item loop ends and the Footer section is printed, TotalQty
and TotalAmount will contain the wanted values.

Printing the Date in the First Iteration Only

For each iteration of the Date data item loop, you want to print the Date to
which the information selected from the Cust. Ledger Entry data item pertains.
You could, of course, just create a Body section for the Date data item and
print the date there (the Period Start field of the data item), but this date
would be printed on a line by itself. Instead, the date should be printed along
with other information on the first line that comes from the Cust. Ledger Entry
data item.

One solution is not to print a Body section for the Date data item at all, but to
print the Date field from the Cust. Ledger Entry data item. This creates another
problem, though: if it is added to the GroupFooter section, the date will be
printed on every line. While this could be an easy way to solve the problem, the
finished report will not be very attractive. Besides, it will be difficult to read the
report if it is 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.

To do so, follow these steps:

1 Design two GroupFooter section as shown in the picture on page 218.

Advanced Sample Reports 221

Chapter 11. Extending the Functionality of Your Reports

2 Declare a global variable of type Boolean and call it IsDatePrinted.

3 Add the following line to the OnPreDataItem trigger of the Cust. Ledger
Entry data item in order to initialize the IsDatePrinted variable before each
iteration of the data item loop:

IsDatePrinted := FALSE;

4 Add the following lines to the OnPreSection trigger of the first GroupFooter
section of the Cust. Ledger Entry section:

IF IsDatePrinted THEN
CurrReport.SHOWOUTPUT(TRUE)
ELSE
CurrReport.SHOWOUTPUT(FALSE);

5 Add the following lines to the OnPreSection trigger of the second

GroupFooter section of the Cust. Ledger Entry section:

IF IsDatePrinted THEN
CurrReport.SHOWOUTPUT(FALSE)
ELSE BEGIN
CurrReport.SHOWOUTPUT(TRUE);
IsDatePrinted := TRUE;
END

What happens is:

1 When a new iteration of the Cust. Ledger begins, a date has not yet been
printed.

2 If the loop generates any output at all, only the second GroupFooter section
(containing the Date text box) will be included as output in the first
iteration.

3 If additional output is generated, only the first GroupFooter section (without

the Date text box) will be printed.

Printing the Selected Range of Dates

The final touch to the report is to add a line at the end of the report that shows
the total number of entries and the total amount of these entries. How to
calculate the figures has already been described. The posting dates are used
as a kind of header in the left margin of the report, however, so the report

222 Advanced Sample Reports

Chapter 11. Extending the Functionality of Your Reports

would look good if the final line of this header could display the range of dates
that the user selected. This is easy to implement:

1 Create a variable of type Text, with a length of 100, and call it DateFilter.

2 Add the following line to the OnPreReport trigger of the report:

DateFilter := Date.GETFILTER("Period Start");

3 Add a text box to the footer section of the Date data item that has DateFilter
as source expression.

When the OnPreReport trigger is executed, the RequestForm will already have
been run. The GETFILTER function returns any filters on the field that is passed
as an argument as a text string.

The Final Report

The report will look like this with sample data:

Advanced Sample Reports 223

 Chapter 11. Extending the Functionality of Your Reports

Date Qty
Document Type Amount

01/15/95 Payment 3 -1,555,252.48

Invoice 1 1,906.25

Credit Memo 1 -2,640.00

Total 5 -1,555,986.23

01/16/95 Invoice 1 10,101.25

Total 1 10,101.25

01/17/95 Credit Memo 1 -6,950.00

Total 1 -6,950.00

01/18/95 Invoice 1 74,658.58

Total 1 74,658.58

01/19/95 Invoice 1 12,162.65

Total 1 12,162.65

01/20/95 Invoice 2 420,327.98

Credit Memo 2 -12,109.57

Total 4 408,218.41

01/22/95 Invoice 1 27,027.30

Total 1 27,027.30

01/23/95 Payment 1 -17,095.25

Invoice 2 149,167.22

Credit Memo 1 -2,230.00

Total 4 129,841.97

01/15/95..01/23/95 Total 18 -900,926.07

Creating a Simple Document

This section will describe how to create a document by using the Report
Designer. The example is a skeletal sales invoice, that is, an invoice that does
not take the complexities of VAT calculations into account and does not test for
a number of conditions that will have to be tested in a real-life situation.
Furthermore, it does not print out all the information you would expect to find
on an invoice.

Defining the Data Model

The two primary tables involved in creating a sales invoice are the Sales
Invoice Header and the Sales Invoice Line tables. Some supporting tables are
used in order to expand the codes used in the invoice tables to more
descriptive texts (Payment Terms, Shipment Method), and the Company

224 Advanced Sample Reports

Chapter 11. Extending the Functionality of Your Reports

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
posted sales invoice, while the Sales Invoice Line table contains the individual
lines that are part of each invoice. The tables are related though a field that is
called No. in the header table (and is the primary key of this table) and
Document No. in the lines table.

In order to define the data model, follow these steps:

1 Create a data item, based on the Sales Invoice Header table.

2 Create another data item, based on the Sales Invoice Line table, and indent
this data item one level.

3 By default, the DataItemLinkReference 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.).

4 Enter the Amount field as the value of the TotalFields property of the Sales
Invoice Line data item, in order to calculate the total amount for all lines on
the invoice.

5 Finally, in order to let the users of the report select a posted invoice to print,
enter the No. field as the value of the ReqFilterFields of the Sales Invoice
Header data item.

This completes the definition of the data model itself. In this report, some
supporting variables are needed in order to access information from tables
that cannot be fitted into the data model.

In order to create the variables, follow these steps:

1 Choose C/AL Globals from the View menu. This will open the form where
you can declare variables.

2 Declare the variables like this:

Advanced Sample Reports 225

 Chapter 11. Extending the Functionality of Your Reports

3 The two last variables must be declared as arrays. Open the Property Sheet
for each variable and set Dimensions to 6 for the variable called CustAddr,
and to 4 for the variable called CompAddr.

This concludes the definition of the data model. Next, a small amount of C/AL
code must be added to the report triggers.

Using the Triggers

This report–in this basic version–needs a very limited amount of C/AL code in
order to function. The picture below actually contains all the code that is
needed.

226 Advanced Sample Reports

Chapter 11. Extending the Functionality of Your Reports

The entire code is in the triggers of the first data item, Sales Invoice Header. In
the OnPreDataItem trigger, the statements work like this

· The first line, CompInfo.GET, retrieves a record–in fact, 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 that trigger uses the COMPRESSARRAY function with the
CompAddr array as an argument, in order to eliminate empty elements from
the array. The reason for doing this is that you cannot be certain that all
fields in the retrieved record have values assigned. If you just printed each
field on a separate line, an empty field would cause an empty line to be
printed.
The code in the OnAfterGetRecord 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 for the reasons described above.
· The last two lines use the GET function (with the codes 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

Advanced Sample Reports 227

 Chapter 11. Extending the Functionality of Your Reports

Method tables. When you design the sections, the full text descriptions can
then be extracted from these records.

Designing the Sections

Now that you have defined the data model and written C/AL code to retrieve
supporting information, you can design the sections. The picture below shows
the Section Designer after the necessary sections have been inserted and the
relevant controls added to the sections.

In the Header section of the Sales Invoice Header data item, you should notice
these points:

· Six text boxes have been inserted with CustAddr[1]..CustAddr[6] as source

expressions. If you compare it with the document reproduced below, you
will see that in this particular invoice, only four of these array elements
contain data. Using COMPRESSARRAY has moved the data up, so to speak.
· Likewise, in the invoice shown below only three of the four elements of the
CompAddr array contain data.
· The text box that prints the posting date does not have the Posting Date as
its direct source expression. Instead, the source expression is the C/AL

228 Advanced Sample Reports

 Chapter 11. Extending the Functionality of Your Reports

expression FORMAT("Posting Date",0,4), which–in the example

here–formats the date as January 19, 1995.
· In the Footer section of the Sales Invoice Line data item, the Amount field is
a totaled field, containing the total of all amounts printed in the Body
sections.
· In the same section, the full text descriptions of Payment Terms and
Shipment Method are printed using PaymentTerms.Description and
ShipmentMethod.Description as source expressions, respectively.

This is how the invoice document looks when sample data is used:

Invoice

Englunds Kontorsmöbler AB CRONUS International Inc.

Box 3319 5 The Ring

Kungsgatan 18 9999 Kugleby

600 03 Norrköbing

January 19, 1995

Due Date 01/31/95

No. 943028

Order No. 941013

No. Description Quantity Unit Price Discount % Amount

1952-W OSLO Storage Unit/Shelf 1 1,589.62771 15 1,351.19

1928-W ST.MORITZ Storage Unit/Drawers 2 3,431.11242 15 5,832.89

1964-W INNSBRUCK Storage Unit/G.Door 2 2,928.56984 15 4,978.57

Total 12,162.65

Payment Terms Current month

Shipment Method Cost Insurance and Freight

A Nonprinting Report
To complete the examples, we will create a nonprinting report. Although you
can achieve the same functionality by writing a codeunit, there are several
good reasons for using nonprinting reports whenever you can:

Advanced Sample Reports 229

 Chapter 11. Extending the Functionality of Your Reports

· The functionality that is available through a request form (prompting for

options, setting filters) is achieved with little effort, while recreating this
functionality in a codeunit is a considerable task.
· Using the features of the Report Designer to prompt for options and to set
filters ensures consistency, not only in the application that you are creating,
but also with the Navision Financials application and add-on products.
· Instead of writing C/AL code to open tables and retrieve records, you just
define a data item.
The report we will create is a simple one: it adjusts prices in the Item table. The
user can set filters on some of the fields in the table in order to select a range
of items by number, by posting group or by vendor, and, of course, can choose
the factor to adjust the prices by.

Defining the Data Model

This report has one data item, based on the Item table.

To define the data model, follow these steps:

1 Create a data item based on the Item table.

2 Set the value of the ProcessingOnly property of the report to Yes.

3 Set the value of the DataItemTableView property of the Item data item to
No. (by using the assist-edit button). Though this is not strictly necessary
for the functionality of the report, it does serve one purpose: it removes the
Sort... button from the request form that will be presented to the user of the
report. As the report will not print anything, the order in which data items
will be run through is irrelevant.

4 Select the fields that the user will be able to filter, by using the assist-edit
button in the ReqFilterFields property:

230 Advanced Sample Reports

 Chapter 11. Extending the Functionality of Your Reports

5 Declare three variables, like this:

· The Window variable, declared as a Dialog type, will be used for printing a
message on the screen while the report runs.
· The Adjustment variable will be used for the value that the user enters in the
request form.
· NewPrice will be used to store an intermediate result.

Creating the Request Form

Step 4 of Defining the Data Model above has already taken care of creating a
request form with a tab where the user can set filters on some of the fields of
the data item. You must add an Options tab, where the user can define the
adjustment factor.

To create an Options tab, follow these steps:

1 Open the Request Options Form Designer by choosing Request Form from
the View menu.

2 Add a text box with a label to the form (to have the label added
automatically, press the Add Label button in the Toolbox before selecting
the Text Box tool).

3 In the Property Sheet of the text box, set the source expression to
Adjustment, the newly created variable.

Advanced Sample Reports 231

 Chapter 11. Extending the Functionality of Your Reports

Using the Triggers

Now that you have defined the data model and designed the request form, you
must add a small amount of C/AL code to the triggers of the Item data item in
order to perform the actual price adjustment. The picture below shows all the
C/AL code that is necessary.

The code functions like this:

· The first statement in the OnPreDataItem trigger opens a window, intended

to show the progress of the report as it is run. (Because the report is
nonprinting, the usual window that shows printing progress is not shown. If
the table is very large, the report may run for a while. Therefore, it is a good
idea to indicate to the user that something is actually happening.)

232 Advanced Sample Reports

Chapter 11. Extending the Functionality of Your Reports

· 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 simply causes the report to
end without doing any processing if the adjustment factor is 0 (zero). If the
adjustment factor were allowed to be zero, then all prices in the table would
be set to zero, which would certainly never be the intention. The statement
used here is a very crude way of handling this situation: in a more polished
version, the user should, for example, have an opportunity to reenter the
adjustment factor (or at least be notified of the reason for quitting the
report run).
· The last three lines in the OnAfterGetRecord trigger actually 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. In
this way, any special processing (for example, updating of other fields that
are related to this field) in the OnValidate trigger of the table field will be
performed. Finally, the MODIFY function is used to commit the change.

Advanced Sample Reports 233

Chapter 11. Extending the Functionality of Your Reports

234 Advanced Sample Reports

Part 5
Codeunits
Chapter 12
Codeunit Fundamentals

This chapter explains what a codeunit is and how

to create one. It also shows you how to use the
functions in a codeunit from other application
objects.

· What Is a C/SIDE Codeunit?

· Creating Codeunits
· Using Codeunits
 Chapter 12. Codeunit Fundamentals

12.1 What Is a C/SIDE Codeunit?

In the previous parts of this book you have seen examples of C/AL code in
forms and reports. This code was always stored in a form or report object. In
simple applications the normal approach is to place the code in the object that
calls the functions, but as your application grows you will often find that you
use the same functions repeatedly. Instead of declaring the same functions
over and over again, it would be useful if you only had to define them once.
This is where the codeunit comes in. Think of a codeunit as a container for C/AL
code that you want to use in many application objects.

In a codeunit you can

store general
functions that are not
directly associated
with any of your other
application objects

In codeunits you can define:

Functions A function is a sequence of C/AL statements, that you define in

order to create new functionality. Within each function you can define local
variables, that is, variables whose scope is limited to the function in which they
are defined.

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 mainly used as structured variables that hold
data temporarily while you work on it. Refer to Defining and Using a Temporary
Table on page 69 for a description of how to create a temporary table.

Each function you add to a codeunit will be shown in a separate section when
you view the file in the C/AL editor.

236 What Is a C/SIDE Codeunit?

 Chapter 12. Codeunit Fundamentals

When you add your

own functions they
will be shown here

All codeunits include two default sections called Documentation and OnRun. In
the Documentation section, you can add optional information about the code
such as the purpose of the codeunit, a version number and so on. In the OnRun
section, you can include code that you want the system execute when the
codeunit is run.

Codeunits Contain Functions but Can Also Be Run

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Besides being a container for functions that can be run individually, a codeunit
can itself be run by writing <Codeunitname>.Run. When you run a codeunit, it
is the code in the OnRun section of the codeunit that will be run.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What Is a C/SIDE Codeunit? 237

 Chapter 12. Codeunit Fundamentals

12.2 Creating Codeunits

You create a new codeunit or modify an existing codeunit in the same way you
create and modify other application objects, that is, by using the Object
Designer.

To create a codeunit:

1 From the menu bar, choose Tools, Object Designer. C/SIDE will open the
Object Designer:

Select codeunit

Press New to create a

new codeunit

Press Design to modify

an existing codeunit

1 Click the Codeunit button in the Object Designer.

2 Click New to create a new codeunit. C/SIDE will open the C/AL editor, where
you can create functions.

To modify an existing codeunit:

1 Click the Codeunit button in the Object Designer.

2 Select the codeunit you want to modify.

3 Click the Design button. C/SIDE will open the C/AL editor, where you can
modify the codeunit by changing existing functions or adding new functions.

238 Creating Codeunits

 Chapter 12. Codeunit Fundamentals

Using the C/AL Editor

The C/AL editor is where you view and edit your code. This editor is designed
to make it easy for you to create and modify C/AL code. When you are in the
editor, you have access to the C/AL Symbol Menu that helps you define C/AL
functions. When you use the C/AL Symbol Menu, you can get help about all
C/AL commands. Select the C/AL function name in the column to the right and
press F1. Read more about the C/AL Symbols Menu in the section Using the
C/AL Symbol Menu on page 244.

When you create a codeunit, the window shows the two default sections
described above (the Documentation and the OnRun section).

From the Object Designer you can open as many codeunits as you like. Each
time you create a new codeunit or open an existing one, it will be displayed in a
separate window. This makes it easy to cut and paste lines of code between
the codeunits.

If you have tried to use other Windows editors, you’ll find the C/AL editor easy
to use. You can access the editing functions both from the Edit menu and from
the toolbar.

Creating Codeunits 239

 Chapter 12. Codeunit Fundamentals

Use the Cut, Copy

and Paste functions
to edit the C/AL code
Write documentation
for the codeunit here

Add your own

functions here

Paste

You can also access

the editing functions
from the toolbar

Cut Copy

When you are working in the C/AL editor, you can use a number of shortcut
keys:

To... Press...
cut the selected text to the clipboard Ctrl+x
copy the selected text to clipboard Ctrl+c
paste the text at the clipboard into the codeunit at the Ctrl+v
cursor position

Defining Variables and Functions in Codeunits

When you have created a new codeunit, the next step is to define the global
variables and functions you need in the codeunit. You use the C/AL Globals
tool for this.

To access the C/AL Globals tool:

240 Creating Codeunits

Chapter 12. Codeunit Fundamentals

Make sure that focus is on the C/AL editor. From the View menu, choose
C/AL Globals. C/SIDE will display the C/AL Globals window:

In the C/AL Globals window, you select whether you want to add a global
variable or a function.

To add a global variable:

1 Click the Variables tab in the C/AL Globals window.

2 Add a name and a type. If the type you select corresponds to a application
object, you also have to add a subtype, that is, the name of a specific object
in the database. If you select text or code you have to define a length for the
variable (the default length is 10 characters for code, and 30 for text). Refer
to Defining and Using a Temporary Table on page 69 for information about
how to create temporary tables.

To add a function:

1 Click the Functions tab in the C/AL Globals window. C/SIDE will display:

Creating Codeunits 241

Chapter 12. Codeunit Fundamentals

Press this button

to define local
symbols such as
parameters,
return value, and
local variables

2 Enter a name for each function you want to add.

3 Press the Locals button to define the parameters, return value and local
variables for each function. C/SIDE will display the C/AL Locals window:

4 For each parameter you have to specify the calling method, a name, and a
data type. You can specify a subtype and a length, but this is optional.

The calling method can be specified as Var, which means that the parameter
is passed by reference rather than by value. The value of a variable can only
be changed by a function when it is passed to the function by reference.
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
affects only the copy and not the variable itself.

242 Creating Codeunits

Chapter 12. Codeunit Fundamentals

If the type you select corresponds to an application object, you also have to
add a subtype, that is, the name of a specific object in the database. If you
select text or code you have to define a length for it (the default length is 10
characters for code, and 30 for text).

5 Click the Return Value tab to define the return value for your new function.
C/SIDE will display:

6 Enter a name for the return value and select a data type from the drop-down
list. You can also select a length, but only if the type is text or code.

7 Click the Variables tab in order to define local variables. C/SIDE will display:

8 For each local variable you must add a name and a type. If the type you
select corresponds to an application object, you also have to add a subtype,
that is, the name of a specific object in the database. If you select text or

Creating Codeunits 243

 Chapter 12. Codeunit Fundamentals

code, you have to define a length for the variable (the default length is 10
characters for code, and 30 for text).

Using the C/AL Symbol Menu

When you write C/AL code in the editor, you can use the C/AL Symbol Menu to
get an overview of:

· all variables defined in the codeunit.

· all C/AL functions.
The information in the C/AL Symbol Menu is divided into columns. The column
to the left shows variable names (if you have defined any) and function
categories. The second column shows the sub-categories, and the third
column (to the right in the picture below) shows the functions in the category
you have selected. You can see the syntax in the bottom of the window, and
you can use the OK or the Apply button to make C/SIDE insert this string in the
C/AL editor.

Use the OK or the

Apply button to
paste the syntax
description into
the editor

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. You can use the right-
arrow button to scroll the symbol menu columns to the right (and the left-arrow
button to scroll them back).

If you use the OK button, the Symbol Menu window is closed automatically; it
stays open if you use the Apply button.

244 Creating Codeunits

 Chapter 12. Codeunit Fundamentals

If you need help about any of the C/AL functions shown in the column to the
right, put the focus on the function name and press F1 to activate the context-
sensitive online C/SIDE Reference Guide.

Compiling and Saving Codeunits

Before the functions in a codeunit can be run, the code has to be compiled and
saved. When you compile the code, the system checks the syntax of the
statements. If the compiler finds any errors in the code it will display a
message.

To compile the code in a codeunit:

1 From the Tools menu, choose Compile.

2 If the system finds any errors in your code it will display a message. Correct
the errors and choose Compile from the Tools menu again.

To save the codeunit:

1 From the File menu, choose Save. C/SIDE will display:

Enter a unique ID and

a Name

Select whether you

want the system to
compile the code
before it is saved

2 Enter an ID number and a name. The number is used as a unique

identification, while the name serves as a label. If you save the codeunit
without compiling it, you won’t be able to run it or call any of its functions.

Why Save without Compiling?

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If you are working on a large and complicated codeunit, you will want to save
you work at regular intervals, even though it is not yet finished and cannot yet
be compiled. In this case, you have to remove the check mark from the
Compiled box before you save.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating Codeunits 245

 Chapter 12. Codeunit Fundamentals

12.3 Using Codeunits

When you use codeunits, you eliminate the need to duplicate code and at the
same time 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.
When you have created a function in a codeunit you can access it as:

<CodeunitName>.<FunctionName>

Example

Assume that you have created a codeunit containing two statistical functions named F and G. The
illustration below shows how to access these functions from a form.

Codeunit named StatFun

F(x:integer)
Begin
...
End
G(x:integer)
Begin
...
End

Any form
...
Result := StatFun.F(3425)+StatFun.G(346);
...

This method is generally applicable. That is, from any application object you
can access functions in other application objects by prefixing the function
name with the name of the application object containing the function.

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 you have created in the codeunit.

All C/AL functions can be used in a codeunit. Notice, however, that you cannot
create a function with the same name as a built-in function. Neither can two or

246 Using Codeunits

Chapter 12. Codeunit Fundamentals

more user-defined functions have the same name (unless they are part of
different application objects).

Using Codeunits 247

Chapter 12. Codeunit Fundamentals

248 Using Codeunits

Chapter 13
Introducing the C/AL Language

This chapter introduces the C/AL language. It

describes how you can use the language to create
functions, and it describes the syntactical rules of
the language.

· What Can You Do with C/AL?

· What are Statements, Expressions, and
Operators?
· Introducing the Elements of C/AL Expressions
· The C/AL Control Language
 Chapter 13. Introducing the C/AL Language

13.1 What Can You Do with C/AL?

The previous parts have shown you how to design various database objects
such as tables, forms and reports. But simply getting these individual objects
up and running is not enough. To turn these objects in to a coherent
application you have to make the database objects work together. C/AL code is
the glue that does this for you. When you are designing professional
applications you will often need specialized functions. Again C/AL makes it
possible to go beyond what C/SIDE does automatically, for example to create
special functions you can use anywhere in the database.

Here are the most important things C/AL lets you do:

Design Your Own Functions Although C/SIDE has a large number of intrinsic
functions, you will sometimes find it convenient or necessary to add your own
functions–for example if the application you are developing repeatedly uses
the same non-trivial processing.

Connect Database Objects C/AL code glues your database objects together.
C/AL includes a number of commands that control how the individual database
objects in your application interact.

Read, Write and Modify Data C/AL includes standard functions for reading,
writing and modifying table data.

250 What Can You Do with C/AL?

 Chapter 13. Introducing the C/AL Language

13.2 What Are Statements, Expressions, and Operators?

In this section the following terms are introduced:

· Statements
· Expressions
· Data types
· Operators
Consider the following C/AL code sample:

Amount := 34 + Total;

This individual code line is also called a statement. The table below illustrates
how the statement can be can broken into smaller elements.

Element Description
34 + Total An expression. In this case the expression consists of an arithmetic operator
(+) and two arguments (34 and Total), which also could be called sub-
expressions. All valid C/AL expressions can be evaluated to a specific value.
:= The assignment operator. When the right-hand side expression has been
evaluated, this operator is used to assign (store) the value in the variable
Amount.
Amount This is called a variable. It is used to reference a memory location where data
is stored.

What Is a C/AL Expression?

An expression is a fundamental C/AL concept. This section describes
expressions and how they are used.

An expression can be used as an argument of a C/AL function. Consider the

C/AL statement below:

Date := DMY2DATE(31, 12, 1996);

This function takes three simple expressions as arguments, 31, 12 and 1996.

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.

All expressions in C/AL are built from:

What Are Statements, Expressions, and Operators? 251

 Chapter 13. Introducing the C/AL Language

· Constants
· Variables
· Operators
· Functions
Depending on the elements in the expression, the evaluation will result in a
value with a C/AL data type. The table below shows some typical expressions.

Expression Evaluates to:

'Welcome to Hawaii' The string 'Welcome to Hawaii'
'Welcome' + ' to Hawaii' The string 'Welcome to Hawaii'
43.234 The number 43.234
ABS(-7234) The number 7234
len1 < 618 TRUE or FALSE depending on the value of len1
The first row shows a text string which is evaluated to itself. The second row
evaluates into a concatenation of the two strings. The third row shows a
decimal number, which is evaluated to itself. The expression in the fourth row
contains a function, which with the given argument is evaluated to the number
7234. The last row shows a comparison between a variable and a numerical
constant.

The above examples show that when C/AL expressions are evaluated, the
results have a specific data type. The next section explains the C/AL data types
in more detail.

Introducing the C/AL Data Types

As you have already seen, variables can be used to store data of various types.
By declaring variables to be of the proper type, you:

· create faster code.

· save space.
· avoid run-time errors due to overflow or impossible type conversions.
For example, if you know that a variable will always contain an integer number
between 0 and 700, you should use an integer variable instead of a decimal
variable. All calculations will be faster because the system uses 4 bytes per
integer operation instead of the 12 bytes that decimal variables require. On the
other hand, you will have to use a data type that can hold all possible values

252 What Are Statements, Expressions, and Operators?

 Chapter 13. Introducing the C/AL Language

needed in your calculations. For example, if you try to store the value 1233.345
in an integer variable you will get a run-time error. C/AL contains a wide range
of data types. These data types can be divided into the following categories:

C/AL Data Types

Fundamental option
integer Numeric
decimal
char
text
String
code
date
time
boolean
binary
Complex BLOB
table

form
codeunit
file
system
dialog
report

Fundamental Data Types

In C/AL there are ten fundamental data types, which are designed to store
boolean values, numbers, text, time and dates.

boolean The values TRUE or FALSE.

integer Used to store integers between -2,147,483,647 and 2,147,483,647.

option This denotes an option value. Option values can freely be converted to
numeric ones. The values range from -2,147,483,647 to 2,147,483,647.

Example

Assume that Number is a numeric variable and that Type denotes a field of type Option in the
Purchase Header table. In the statement below the option value is converted to a number:

Number := "Purchase Header".Type;

What Are Statements, Expressions, and Operators? 253

Chapter 13. Introducing the C/AL Language

Example

This example illustrates how the possible values of an option field can be used as constants in your
C/AL code:

“Purchase Header”.Type := “Purchase Header”.Type::Invoice;

decimal 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.

date Denotes dates ranging from January 1, 0 (the year zero) to December 31,
9999. An undefined date is expressed as 0D. All dates have a corresponding
closing date. The closing date for a given date is regarded by the system as a
period following the given date but before the next normal date. Thus a closing
date is sorted immediately after the corresponding normal date but before the
next normal date.

time Denotes a time. An undefined time is expressed as 0T. Any time in the
range 00:00:00 to 23:59:59.999 is valid.

char 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 with a number type variable.

Example

You can assign a constant string of the length 1 to a char variable:

C := "A";

Example

You can also assign a single char in a text, code or binary type variable to a char variable:

C := S[2];

When using text and code

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 can be seen as the upper limit for the number of
characters in the string, while the actual length describes the number of
characters used in the string.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
text Denotes a text string. The maximum length of the string ranges from 1 to
250 characters. You can index any character position in a string–for example

254 What Are Statements, Expressions, and Operators?

 Chapter 13. Introducing the C/AL Language

A[65] refers to the 65th character in the variable called A. The resulting values
will be of type char. The length of a variable of type text corresponds to the
number of characters in the text. An empty text string thus has the length 0.

The table below illustrates some typical examples of text strings. In these
examples it is assumed that the variable t is of type text and has a maximum
length of 6.

Assignment Results in...

t := 'AbC'; The variable t now contains 'AbC'.
t := '123456abx'; Results in a run-time error, because the length (9) exceeds the
maximum length (6).
code Denotes a special type of text string. When a given text is assigned to a
code type variable, the text is transformed to uppercase, and 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 type char. The
maximum length of a code type variable ranges from 1 to 250 characters. The
length of a code type variable always corresponds to the number of characters
in the text without leading and trailing spaces.

Example

The table below shows some typical examples of code string assignments. In the examples, it is
assumed that the variable c has the type code, and the maximum length 4.

Assignment The variable c now contains... The length is...

c := 'AbC'; 'ABC' 3
c := '1'; '1' 1
c := ''; '' (empty string) 0 (zero)
c := ' 2 '; '2' 1
c := '1 2'; '1 2' 3

Descriptional Data types

In order to describe the syntax of the C/AL-language, some descriptional data
types are used. It is important to stress that these are not real system data
types, but are used in the C/SIDE documentation for descriptional purposes
only.

The table below summarizes the correspondence between the descriptional

data types and the simple C/AL data types.

What Are Statements, Expressions, and Operators? 255

 Chapter 13. Introducing the C/AL Language

Descriptional data type Includes these system data types...

Numeric char, integer, option, and decimal
String text and code

Complex Data Types

C/AL contains seven complex data types. Complex data types are used when
you need to work with, for example, records in tables, pictures (bitmaps) or
disk files. As C/AL is object oriented, each complex data type can include both
member variables and member functions.

BLOB This 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 normally determined by your
systems disk storage capacity, as the upper limit is 2GB.

record This is a complex data type, consisting of a number of simpler

elements called fields. A record corresponds to a row in a table. Each field of
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.

form Variables of this data type are used to store forms. This is a complex
data type which can contain a number of simpler elements called controls.
Controls are used to display information to the user or to receive user input.

codeunit Variables of this data type are used to store codeunits. This is a
complex data type which can contain a number of user-defined functions.

file Variables of this data type give you access to operating system files.

dialog Variables of this type are used to store dialog windows. A number of
functions are available for manipulating dialogs.

report Variables of this data type are used to store reports. This is a complex
data type that can contain a number of simpler elements called controls.
Controls are used to display information to the user.

Creating Arrays of Variables

It is possible to create 10-dimensional variables, using the simple and complex
data types presented above. There are no limitations on how many elements a

256 What Are Statements, Expressions, and Operators?

Chapter 13. Introducing the C/AL Language

dimension can contain but an array variable can never have more than
1,000,000 elements in all. 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 will occur.

Example

Assume that Foo is a one-dimensional array variable of the Integer type, with the dimension 10.

To index the first element, use Foo[1]. To index the last element, use Foo[10].

Example

Assume that Bar is an array variable of type Date with the dimensions 2x3x4. Then Bar has 24
elements.

To index the first element, use Bar[1,1,1]. To index the last element, use Bar[2,3,4].

What Are Statements, Expressions, and Operators? 257

 Chapter 13. Introducing the C/AL Language

13.3 Introducing the Elements of C/AL Expressions

The previous sections have introduced you to C/AL expressions and data
types. The aim of this section is to present the basic elements of C/AL
expressions. The following subsections will briefly discuss:

· Constants
· Variables
· Operators
· Functions
We start by defining ranges and properties of constants in 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.

Entering Values in C/SIDE

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Beware that in the examples below, numbers such as 2,147,483,647 and
999,999,999,999,999.99 cannot be entered in the C/AL system in this form.
The commas are only used to increase the legibility of this document. If you
use commas when you enter numbers in the C/AL editor, a compilation error
will occur.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
boolean constant A boolean constant may 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 '.' 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.

258 Introducing the Elements of C/AL Expressions

 Chapter 13. Introducing the C/AL Language

date constant A date constant is written as six or eight digits followed by the
letter 'D' (the date constant expressing 'undefined date' is, however, 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, however, 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 that is placed in

apostrophes ('). '' indicates the empty text string. If you need to include an
apostrophe in the text, you must enter it as two single apostrophes (''), that is,
a text constant which is shown as an apostrophe is written as four apostrophes
('''').

The table below illustrates different types of C/AL constants:

Constant Description
TRUE boolean constant
50000 integer constant
-23.7 decimal constant
122196D date constant (December 21, 1996)
141230T time constant (the time 14:12:30)
'ABC’ string constant

Using Variables in C/AL

There are two types of variables in the C/AL system: user-defined variables
and system-defined variables.

User-defined variables are ones you define when you create new C/AL code.
You can define variables that are global to all functions within a codeunit and
variables that are local to each function in a codeunit. Both types of user-
defined variables are local to the codeunit in which they are defined. These
variables can be used to store information at runtime, and the values can be
changed as desired.

In addition, a number of predefined variables are provided by the system.

These variables are automatically maintained by the system and are called
system-defined variables. The system-defined variables are, for example, Rec,
xRec, CurrForm and CurrReport.

Introducing the Elements of C/AL Expressions 259

 Chapter 13. Introducing the C/AL Language

When the system is running, it executes code in functions and triggers, for
example entry-processing code for a table. Before the code is executed, the
system automatically assigns values to the associated system-defined
variables, and in the triggers and the local functions the values of these
variables can be used.

During the execution of triggers and functions, the system-defined variables

can be used just like normal variables (new values can be assigned to them).
That is, the values of the system-defined variables are not updated by the
system while the C/AL code is being executed, but only before the function or
trigger is executed.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
the value in a system-defined variable does not propagate backwards. In other
words the user cannot use a system-defined variable to modify the state of the
system.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Variable Names
Variable names must be unique, that is, two user-defined variables with the
same name are not allowed in a C/AL codeunit. Furthermore, you cannot have
user-defined and system-defined variables with the same name. Uppercase
and lowercase letters are not distinct, that is Smith and SMITH refer to the
same variable. In standard Pascal notation, a variable name (an identifier) can
only be written as an unbroken word. This restriction is relaxed in C/AL: here it
is also possible to use special characters (for example spaces) in a variable
name.

Observe the following basic restrictions:

· The maximum length of a variable name is 30 characters.

· A variable name must not be the same as the name of a C/AL function name
or a reserved word. Please note that this rule applies to both uppercase and
lowercase spellings. For example, neither BEGIN nor begin is valid.
All ASCII characters are valid in variable names, except the following:

· Control characters (ASCII 0-31, 255)

· The character " (ASCII 34)

260 Introducing the Elements of C/AL Expressions

Chapter 13. Introducing the C/AL Language

When naming a variable, be careful to note that characters cannot be

combined freely unless you encapsulate the variable name in double quotes,
as in "Customer No.". If you don’t, you should name variables like this:

The first character must be:

· a letter in the range: a..z, A..Z (ASCII 97-122, 65-90), or

· an underscore (ASCII 95),
...followed by a maximum of 29 characters, which can be either

· a letter a..z, A..Z (ASCII 97-122, 65-90)

· an underscore (ASCII 95), or
· digits in the range 0..9 (ASCII 48-57).
As mentioned, it is also possible to include one or more special characters
(spaces, and so on) in a variable name in C/AL, but then the entire variable
name must be put in double quotes. In this case, the name can contain any mix
of letters, digits and special characters.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
the double quotes are not part of the variable name, but are necessary in order
to avoid a compile-time error.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Here are a number of examples showing valid variable names:

· Customer
· StockGroup1
· "@Vendor"
· "1st AddressLine"
· "Purchase/Sales"
· "Sales In GBP"
· " YesCrazy Name1Ñ3"
...and the following are examples of invalid variable names

· 34467
· 23"Tubes
· Stock Group4

Introducing the Elements of C/AL Expressions 261

 Chapter 13. Introducing the C/AL Language

· "Sale"s in GBP"
· )-Names
· END

Initialization
Variables are automatically initialized before C/AL code is executed. A boolean
variable is set to FALSE and numeric variables are set to the default value zero,
while strings (text and code) are initialized to the value '' (the empty string)
and date and time variables are set to the undefined time 0T and the undefined
date 0D, respectively.

As previously mentioned, the system automatically handles the system-

defined variables. This also includes the necessary initialization. This means
that no actions are required by the user before the system-defined variables
can be used.

Assignment and Type Conversion

Assignment of values can be performed in one of two ways:

· As parameter assignment, for example FUNCTION(Expression). The

resulting data type of the evaluation of the expression must correspond to a
specific data type or have a type which can be converted automatically to
the correct type. (For a detailed discussion about evaluation and type
conversion in expressions, please refer to appendix B, Type Conversion, on
page 327.)
· By using the assignment operator ':=' (for example Variable := Expression).
Generally, the resulting data type of the evaluation of the right-hand side
expression must be of the same type as the variable (left operand) or have a
type which can be converted automatically to the type of the left operand.
Automatic type conversion in assignments takes place when:

· A parameter in a function call does not have the correct type. This occurs for
instance if a function that is supposed to be called with an integer argument
is called with, for example, a decimal argument.
· The evaluation of the expression on the right-hand side of an assignment
operator (:=) results in a type that differs from the type of the variable on
the left-hand side.

262 Introducing the Elements of C/AL Expressions

Chapter 13. Introducing the C/AL Language

The automatic type conversion in assignments can freely take place between
the following numeric data types, provided overflow does not occur:

char integer decimal

The automatic type conversion in assignments can also freely take place
between the String data types:

code text

All the above has been based on simple variables. Nevertheless, 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(s) of the right-hand
expression must correspond to the dimension(s) of the variable.

Notice That...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
the type conversion that takes place in assignments can cause run-time errors
even though the types are convertible. A run-time error can occur in an
assignment if the converted value is outside the valid range for the left-hand
side variable. Correspondingly a run-time error can occur if the converted value
is outside the valid range for a parameter in a function call.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example

Let the variable A be defined as a one-dimensional array with four text type elements with the
maximum length 15. A value could be assigned to the second element in the array as shown below:

A[2]:= 'Enter your name';

Example

Result is an option variable, while Amount and Total both are decimal variables.
Consider the following assignment statements:

Amount := 10;
Total := 4;
...
Result := Amount + Total;

The above code can always be compiled, but a run-time error will occur if the result of the right-hand
side expression 'Amount + Total' exceeds the valid range of the datatype of the left-hand side
variable Result, that is, outside the range -2,147,483,647 to 2,147,483,647.

Introducing the Elements of C/AL Expressions 263

 Chapter 13. Introducing the C/AL Language

Valid Assignments
The table below shows whether it is possible to assign the value of an
expression of a given type to a variable of a given type:

Expression Type
Variable boolean char option Integer decimal date time text code
Type
boolean c j j j j j j j j
char j c i i i j j j j
option j c c c i j j j j
integer j c c c i j j j j
decimal j c c c c j j j j
date j j j j j c j j j
time j j j j j j c j j
text j j j j j j j i i
code j j j j j j j i i

c The assignment is valid

i The assignment is valid, but overflow may occur
j the assignment is invalid

Using Operators in C/AL

Operators can be used in expressions to combine, investigate and manipulate
values and data elements. This section describes the function of the operators
in C/AL. The table below 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

264 Introducing the Elements of C/AL Expressions

Chapter 13. Introducing the C/AL Language

C/AL operator Meaning

>= 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

The '+' and the '-' operators can be used both as unary and binary operators,
the 'NOT' operator only as an unary operator, while all other operators are
binary.

Most of the above operators can be used on different data types. The action of
these operators may depend upon the data type of expression they are used
on. Below are some typical examples

Example

The '+' operator used as a binary operator:

number + number

This returns the sum of the numbers, that is, a result of the type number.

Example

The '+' operator used as a binary operator:

string + string

This returns the concatenation of the strings, that is, a result of the type string.

Example

The '+' operator can be used as an unary operator to indicate sign, for instance:
+ 34545

You can read more about the function of each operator in the appendix Type
Conversion, on page 327., which explains the type conversion mechanisms in
C/AL.

Introducing the Elements of C/AL Expressions 265

 Chapter 13. Introducing the C/AL Language

Operator Hierarchy
The operators just discussed are organized in a hierarchy that determines the
order in which the operands in a given expression will be evaluated. The list
below shows the precedence order 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)

The example below illustrates the effect of the operator hierarchy. The
expressions, which apparently are the same, will produce different results.

Example

The expression

2 + 3 * 4

is evaluated to 14, whereas the expression

(2 + 3) * 4

is evaluated to 20.

Function Calls
C/AL has a number of functions for different purposes, such as string handling,
text formatting, database handling and so on. Some of these functions differ
from standard Pascal, as it is possible to use a variable number of parameters.
In a function call, the parameters are separated by commas, and the optional
parameters may be omitted from the right.

This means that if the function has, for instance, 3 optional parameters, then it
is not possible to omit the second without omitting the third.

266 Introducing the Elements of C/AL Expressions

Chapter 13. Introducing the C/AL Language

Example

The fictitious function

FUNCTION([Optional1] [, Optional2] [, Optional3])

can be called as

FUNCTION(Optional1, Optional2)

but not as

FUNCTION(, Optional2, Optional3)

Example

ABS is a typical example of an C/AL function with a fixed number of parameters (1).

Value := -1033;{A negative integer value}

PositiveValue := ABS(Value);{Calculate the positive value 1033}

Example

The function DMY2DATE is a typical example of a function which can be called with a variable
number of parameters

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, as the second and third parameter are optional. When the second and third parameters
are not used, the system uses values from the system date as default.

Introducing the Elements of C/AL Expressions 267

 Chapter 13. Introducing the C/AL Language

13.4 The C/AL Control Language

This section describes the basic structures in the control language in C/AL and
how to use them. All the C/AL programs 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. You may
have to repeat the execution of one or more statements a number of times, and
in another situation you may have to make the execution of a certain statement
conditional.

The control structures in C/AL are divided into the following main groups:

· Compound Statements
· Conditional Statements
· Repetitive Statements
· WITH Statements

Using Compound Statements

In some cases, the C/AL syntax will only allow use of a single statement. If you
have to execute more than one simple statement in such a case, the
statements can be turned into a compound statement, by ‘encapsulating’ the
statements between the keywords BEGIN and END. The syntax is

BEGIN
<Statement 1>;
<Statement 2>;
.
.
<Statement n>;
END

The individual statements are separated by a semicolon. In C/AL and Pascal 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.

The above BEGIN END structure is also called a block. Blocks can be very useful
in connection with the other control structures to be discussed in the following.

268 The C/AL Control Language

 Chapter 13. Introducing the C/AL Language

Conditional Statements
By using a conditional statement, you can specify a condition and one or more
commands to be executed, according to the evaluation of the condition: TRUE
or FALSE. There are two types of conditional statements in C/AL:

1 IF THEN [ELSE], when there are 2 choices.

2 CASE, when there are more than 2 choices.

The IF THEN ELSE Control Structure

This statement type has the following syntax:

IF <Condition> THEN <Statement1> [ ELSE <Statement2> ]

which means

If <Condition> is true, <Statement1> is executed. If <Condition> is false,

<Statement2> is executed.

As defined earlier, the square brackets around ELSE <Statement2> means that
this part of the statement is optional.

This statement is used when different actions are to be executed, depending

on the evaluation of the <Condition>.

It is possible to build even more complex control structures by nesting IF THEN

ELSE statements. A typical example is

IF <Condition1> THEN IF <Condition2> THEN <Statement1> ELSE

<Statement2>

If <Condition1> is false, nothing is executed. If <Condition1> and

<Condition2> are both true, <Statement1> is executed. If <Condition1> is
true, and <Condition2> is false, <Statement2> is executed. Please note that a
semicolon preceding an ELSE is not allowed.

Several nested IF THEN ELSE statements may seem confusing but a general
rule is that an ELSE belongs to the last IF that lacks an ELSE.

Here are some examples of IF THEN ELSE statements:

Example

Illustration of an IF statement without the optional ELSE part:

IF Amount < 1000 THEN Total := Total + Amount;

The C/AL Control Language 269

 Chapter 13. Introducing the C/AL Language

Example

(1)...
(2) IF Amount < 1000
(3) THEN BEGIN
(4) IF I > J THEN Max := I
(5) ELSE Max := J;
(6) Amount := Amount * Max;
(6) END
(7) ELSE
(8)...

A common error for the C/AL newcomer is to put an extraneous semicolon at the end of a line before
an ELSE (line 4). As mentioned above, this is not valid according to the syntax of C/AL, as the
semicolon is used as a statement separator. (The end of line 4 is inside the inner IF statement).

The CASE Control Structure

The syntax of the CASE statement is

CASE <Expression> OF
<Value set 1> : <Statement 1>;
<Value set 2> : <Statement 2>;
...
...
<Value set n> : <Statement n>;
[ELSE <Statement n+1>]
END;

In the above definition, the <Expression> cannot be a record, and the <Value
set> must be an expression or a range.

CASE statements are also called multiple option statements and are typically
used when a selection between more than two different actions is to be made.
The function of the CASE statement is as follows:

· The <Expression> is evaluated, and the first matching value set causes the
associated statement, if any, to be executed.
· If none of the value sets matches the value of the expression, and the ELSE
part has been omitted, no action will be taken; but if the optional ELSE part
is used, then the associated statement will be executed.
The type of the value sets must be the same as the type of <Expression> or at
least convertible to the same type.

270 The C/AL Control Language

 Chapter 13. Introducing the C/AL Language

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
the data type of the value sets will be converted to the same data type as the
evaluated <Expression>, if necessary. This type conversion may cause an
overflow at run time if the resulting data type cannot hold the values of the
value sets.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example

This C/AL code sample will print various messages depending on the value of Number. If the value
of Number does not match any of the entries in the CASE structure, the ELSE entry will be used as
default.

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

Using Repetitive Statements

A repetitive statement is also known as a loop. The looping mechanisms in
C/AL are:

· FOR, which repeats the inner statement until a counter variable equals the
maximum or minimum value specified.
· WHILE, which repeats the inner statement while the specified condition is
TRUE. The statement in a loop of this type is repeated 0 or more times.
· REPEAT, which 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.

The FOR TO/DOWNTO Control Structure

The syntax of the FOR TO (and FOR DOWNTO) statement is

FOR <Control Variable> := <Start Number> TO <End Number> DO

<Statement>

<Control Variable>, <Start Number> and <End Number> must be boolean,

number, time or date data types.

FOR statements are used when a code block is to be executed a specific

number of times. A control variable is used to control the number of times the

The C/AL Control Language 271

 Chapter 13. Introducing the C/AL Language

code block is executed. The <Control Variable> may be increased or decreased

by one, according to whether TO or DOWNTO is used.

When declaring the type of the <Control Variable>...

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
it should be noticed that when the system executes the FOR statement, the
<Start Number > and <End Number> will be converted to the same datatype
as <Control Variable>, if necessary. This type conversion may 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. Correspondingly, the
<Statement> will not be executed in the FOR DOWNTO loop if the start value is
less than the end value.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
if the value of the control variable is changed inside the FOR loop, the behavior
of the system is not predictable. Furthermore, the value of the control variable
is undefined outside the scope of the FOR loop.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example

The following FOR loop uses an integer control variable named Count.

FOR Count := 1000 TO 10000000000000000 DO

When the above statement is executed, a run-time error will occur because the system tries to
convert the start and end values to the same type as the control variable; but as Count has been
declared as an Integer variable, an error will occur when 10000000000000000 is to be
converted, because this end value is outside the valid range for Integers.

Example

This example illustrates nesting of FOR statements:

FOR I := 1 TO 5 DO
FOR J := 1 TO 7 DO
A[I,J] := 23;

The two FOR statements above could be used to initialize every element in a 5 x 7 array with the
value 23.

The WHILE DO Control Structure

The WHILE DO statement has the following syntax:

WHILE <Condition> DO <Statement>

272 The C/AL Control Language

 Chapter 13. Introducing the C/AL Language

If <Condition> is TRUE, <Statement> is executed repeatedly, until

<Condition> becomes FALSE. If <Condition> is FALSE from the start,
<Statement> is never executed.

When a block of code is to be repeated as long as an expression is TRUE, the

WHILE DO statement may come in handy.

Example

The C/AL code below increases the variable i until it equals 1000:

WHILE i < 1000 DO i := i + 1;

The REPEAT UNTIL Control Structure

The syntax for the REPEAT UNTIL statement is:

REPEAT <Statements> UNTIL <Condition>

<Statements> will be executed repeatedly until <Condition> is TRUE.

This might at first glance seem to function just like a WHILE control structure,
but as the REPEAT UNTIL statement is executed from left to right, it is easily
seen that the <Statements> always will be 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–implying that if the first evaluation of <Condition> returns FALSE,
then no statements will be executed.

Example

This is a typical example of a REPEAT UNTIL control structure:

Count := 0;
IF Customer.FIND(`-') THEN
REPEAT
Count := Count + 1;
UNTIL Customer.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 NEXT is called, it steps one record forward. When
NEXT = 0 there are no more entries in the table and the system exits the loop.

The C/AL Control Language 273

 Chapter 13. Introducing the C/AL Language

The EXIT Statement

The EXIT statement is used to control the flow of the execution. The syntax of
an EXIT statement is:

EXIT([<Value>])

An EXIT statement is used to interrupt the execution of a C/AL trigger. The

interruption will take place even when the execution is inside a loop or a
similar structure. The EXIT statement is also used when a local function is to
return a value: EXIT(Value).

Using EXIT without a parameter in a local function corresponds to using the

parameter value 0. That is, the C/AL function will return the value 0 or '' (empty
string).

A compile-time error will occur if EXIT is called with a return parameter from:

· system-defined triggers.
· local functions that are not supposed to return a value.
Example

The following illustrates the use of the EXIT statement in an arbitrary local function. Assume that the
IF statement is used to detect an error. If the error condition is met, the execution is stopped and the
local function returns the error-code 1.

FOR I := 1 TO 1000 DO
BEGIN
IF Amount[I] < Total[I] THEN EXIT(1);
A[I] := Amount[I] + Total[I];
END;

The WITH Statement

The syntax for the WITH statement is:

WITH <Record> DO <Statement>

When you work with records, addressing is carried out as record name, dot
(period) and field name: <Record>.<Field>

If you work continuously with the same record, you can use WITH statements.
When you use a WITH statement, it is only necessary to specify the record
name once.

274 The C/AL Control Language

 Chapter 13. Introducing the C/AL Language

Within the scope of <Statement>, fields in <Record> may be addressed

without specification of the record name.

Several nested WITH statements may be used. In case of identical names, the
inner WITH will overrule the outer WITH-statements.

Example

This example shows two ways of writing the same code:

CustomerRec.No := '1234';
CustomerRec.Company := 'Windy City Solutions';
CustomerRec.Manager := 'Joe Blow';
CustomerRec.Address := '1241 East Druid Avenue';
CustomerRec."State and Zip":= 'Chicago, IL 60079';

Another way of expressing the same is:

WITH CustomerRec DO
BEGIN
No := '1234';
Company := 'Windy City Solutions';
Manager := 'Joe Blow';
Address := '1241 East Druid Avenue';
"State and Zip" := 'Chicago, IL 60079';
END;

How to Annotate Your Programs

You can insert comments about the code or ‘outcomment’ parts of your code to
prevent execution.

There are two ways to insert comments:

· Use '//' to insert a single line comment. When the compiler encounters the
'//' symbol in your code, it interprets the rest of the line as a comment.
· Use '{' and '}' to mark the beginning and end, respectively, of a block of
comments.
Any number of nested comments may occur. In such cases, the comment runs
from the first comment start to the last comment end.

The C/AL Control Language 275

Chapter 13. Introducing the C/AL Language

Example

{
This is a sample comment which is ignored by the C/AL compiler
}

Example

// This is also a sample comment which is ignored by the C/AL compiler

Example

{ This comment { is partly inside } another comment }

Example

The final example illustrates what you shouldn’t do:

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:

A := 34;
B := 56; //*******************
C := 345; //* Do it this way! *
D := 781; //*******************

276 The C/AL Control Language

Chapter 14
Using C/AL

This chapter describes some aspects of using

C/AL. The first section give advice on using the
system-defined variables. The second describes
how to handle functions that may or may not
generate run-time errors, depending on how they
are used. The last, and largest, section provides
an overview of a subset of C/AL functions and
examples of how to use them. The functions in
this subset are the most commonly used, and if
you understand how to use them, you will be able
to create quite sophisticated C/SIDE applications.

· System-Defined Variables
· Handling Run-Time Errors
· The Essential C/AL Functions
 Chapter 14. Using C/AL

14.1 Overview
This chapter describes how to use C/AL. The first sections concentrate on
giving some advice on the things you should consider when you use C/AL–the
most important subject being where you place the code.

The concepts of system-defined variables and run-time errors are explained,

and the final, larger, section describes and gives examples on how to use a
subset of C/AL functions–a subset that experience has shown will be the set of
functions that developers will use most often.

Where to Write C/Al Code

As described in previous chapters, almost every object in C/SIDE has triggers
where C/AL code can be placed. In summary, you have triggers for:

· Tables
· Table fields
· Forms, including request options forms
· Form controls
· Reports
· Data items
· Sections
The execution of C/AL can also be initiated from:

· Command buttons
· Menu items
You can also place C/AL code in codeunits and call it from code in any of the
locations mentioned above.

As you can see, you can put C/AL code in a large number of places and initiate
or trigger its execution in many ways. You should not, however, choose a
location for your C/AL code at random. A few simple guidelines should be
followed:

· In general, place the code as close as possible to the object it operates on.
This implies that code that modifies records in the database should
normally be placed in triggers of the table fields that are involved.

278 Overview
 Chapter 14. Using C/AL

· In reports, there should always be a clear distinction between logical and

visual processing, and you should position 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 controls or whether the
section should be printed. On the other hand, you should never place data-
manipulating code in section triggers.
· The principle of placing code near to the object it operates on can be
overruled in some situations. One very good reason is security. Users do not
have direct access to tables with sensitive data–such as the general ledger
entry and register tables. If you place the code that operates on the general
ledger in a codeunit and give the codeunit access to the table and the user
the right to execute the codeunit, you will not compromise the security of
the table, and the user will still be able to access the table.
· There are other reasons than security for putting a posting function like the
one described in the item above in a codeunit. A function that is placed in a
codeunit can be called from many places in the application–perhaps
including some that you did not have in mind when you first designed the
application.

Reusing Code
Perhaps the most important reason for placing C/AL code consistently, and as
close to the objects it manipulates as possible, is that it lets you reuse code.
Reusing code make it faster and easier to develop applications, but this alone
is not the most important reason for reusing code whenever you can. 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 the code has to be changed, you could easily either forget about
some of these controls or make a mistake when editing one of them.

Overview 279
 Chapter 14. Using C/AL

14.2 System-Defined Variables

C/SIDE automatically declares and initializes a number of variables for use in
application development. These are the system-defined variables

Variable Comments
Rec When a record is modified, the Rec variable contains the current record
xRec (including the changes that are made), while the xRec variable contains the
original values (before the changes).
CurrForm Refers to 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 Refers to the current report in the same way as CurrForm refers to the
current form.
RequestOptionsForm Refers to the request options form of the current report.
CurrFieldNo The field number of the current field in the current form–retained for
compatibility reasons.
In addition, some triggers (for example, the OnFormat trigger of a control) have
a parameter that is defined as a local variable by the system.

Example

You could put the Rec/xRec pair of records to use in a situation like this: in an application, data is
stored in two tables, a header table and a lines table. The header table contains general information
about, for example, sales orders, while the lines table contains the specific order lines. On the form
where the user enters information in the header table there are fields that contain the customer’s
address. These fields are related to a Customer table, and can be filled out 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 (name, address, and so forth) are retrieved
from the Customer table when the Customer No. field is validated.

Now, should the user be able to change the customer number? In some situations the answer would
be yes, in others no. If the order has already been shipped, the answer should definitely be no, but
there could be situations where it would be yes–it should, for example, be possible to correct an
erroneous number on an order that has not been processed any further.

You could do something along these lines

- When validating the customer number field, check whether the order has been shipped.

- If it has, compare the customer number fields in the xRec and Rec records. If they differ, reject the
change.

In real life, you would certainly add some more checks and some user dialog, but this is the basic
idea.

280 System-Defined Variables

 Chapter 14. Using C/AL

14.3 Handling Run-Time Errors

In the chapter on debugging (chapter 15, C/AL Debugging), the section Other
Run-Time Errors on page 304 describes how to handle functions that return a
boolean value that can be processed or ignored.

When you use these functions, four different scenarios are possible, as
depicted in this table

Return value is ignored Return value is processed

Function succeeds Execution continues Execution continues
Functions fails A run-time occurs Execution continues, and you must
handle the situation yourself
A typical example of a function that will or will not produce a run-time error,
depending on how you handle the return value. is GET. The syntax is:

[Ok :=] Record.GET([Value1], [Value2 ],...)

Ok is a boolean value, which will be TRUE if the record is found and FALSE
otherwise. If GET is used as below, and no record is found,

Customer.GET("Customer Number");

a run-time error will occur. If, on the other hand, GET is used as below, and no
record is found,

IF Customer.GET("Customer Number") THEN

....
ELSE
...

execution will continue. In this case you will need to handle the situation
yourself in the ELSE part of the statement.

Handling Run-Time Errors 281

 Chapter 14. Using C/AL

14.4 The Essential C/AL Functions

Although there are more than 100 functions in C/AL, you will find that you use a
limited set of these functions repeatedly, while you use the rest of the
functions only occasionally. That is to say: during basic application
development you use perhaps no more than 20 different functions. This does
not mean that the rest of functions are obsolete or that you will never use
them–but it does mean that if you are comfortable with this set of essential
functions, you will be able to go a long way in C/AL programming. As you need
to add more specialized functionality to your applications–or you want to
round them off by adding ‘bells and whistles’–you can familiarize yourself with
the full set of functions.

Below are some examples of how to use this set of essential functions. You
should, however, always refer to the online C/SIDE Reference Guide for full and
updated information on any C/AL function.

Searching For Records

The three functions described in this section are used to search for records.
When you are going to search for records, it is important to remember the
difference between GET and FIND–and how you can use FIND and NEXT in
conjunction.

GET GET retrieves one record, based on the value of the primary key. That is, if the
No. field is the primary key of the Customer table, GET can be used like this:

GET(Customer,'4711');

The result will be that the record of customer 4711 will be retrieved. GET is one
of those functions that will produce a run-time error if it fails and the return
value is not inspected by the code, and otherwise not. This means that your
actual code would probably look more like this:

IF GET(Customer,'4711') THEN
.... // do some processing
ELSE
.... // do some error processing

GET searches for records, regardless of current filters, and it does not change
any filters. In other words: GET always searches among all records in a table.

282 The Essential C/AL Functions

 Chapter 14. Using C/AL

FIND An important difference between GET and FIND is that FIND respects (and is
limited by) the current setting of filters. Further differences are that FIND can
be instructed to look for records where the key value is equal to, larger than or
smaller than the search string, and finally, FIND can find the first or the last
record (given the sorting order defined by the current key).

You can use these features in various ways. When developing applications
under a relational database management system, you will often have one-to-
many relationships between tables. An example could be the relations
between an Item table, which registers items, and a Sales Lines table, which
registers the detail lines from sales orders. Obviously, 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 deleted while there are still open sales
order records that include the item. You can use FIND to check this.

To do this, insert the following code in the OnDelete trigger of the Item table:

SalesOrderLine.SETCURRENTKEY("Document Type",Type,"No.");
SalesOrderLine.SETRANGE(
"Document Type",SalesOrderLine."Document Type"::Order);
SalesOrderLine.SETRANGE(Type,SalesOrderLine.Type::Item);
SalesOrderLine.SETRANGE("No.","No.");
IF SalesOrderLine.FIND('-') THEN
ERROR(
'You cannot delete because there are one or more outstanding
salesorders that include this item.');

NEXT NEXT is often used with FIND to step through records of a table, as in this
fragment:

FIND('-');
REPEAT
// process record
UNTIL NEXT = 0;

Here, FIND is used to go to the first record of table. Afterwards, NEXT is used to
step through every record, until there are no more (then, NEXT returns 0
(zero)).

The Essential C/AL Functions 283

 Chapter 14. Using C/AL

Sorting and Filtering Records

These functions are used to filter records in a table, that is: to 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 forth. You will also find a description of
how to change the sorting of the records in a table.

SETCURRENTKEY This function is used to select a key for a record, thereby setting the sorting
order that will be used for the associated table. SETCURRENTKEY has this
syntax:

[Ok :=] Record.SETCURRENTKEY(Field1, [Field2],...)

You should have these points in mind when you use SETCURRENTKEY:

1 Fields that are not active are ignored

2 When searching for a key, C/SIDE selects the first occurrence of the
specified field(s).

For example, even if you specify only one field as a parameter when calling
SETCURRENTKEY, the key that is actually selected may consist of more fields; if
several keys have as their first component the field that you specified, you may
not get the key that you think you will.

If no keys can be found that include the specified field(s), a run-time error will
occur unless you test the boolean return value of SETCURRENTKEY in your
code. If you do test the return value, you will have to decide what to have the
program do if the function returns FALSE, because without a run-time error, the
program will continue to run even though no key has been found.

SETRANGE This function is used to set a delimitation on a field–that is, a simple filter. The
syntax is:

Record.SETRANGE(Field [,From-Value] [,To-Value]);

as in this example:

Customer.SETRANGE("No.",'10000','90000');

which would limit the Customer table by selecting only those records where
the No. field has a value between 10000 and 90000.

SETRANGE will remove previous filters. If used without the From-Value/To-

Value parameters, the function can be used to remove any filters that might

284 The Essential C/AL Functions

 Chapter 14. Using C/AL

already be set. And, finally, if only From-Values is used, To-Value will be set to
the same value as From-Value.

SETFILTER SETFILTER sets a filter in a more general way than SETRANGE. SETFILTER has
this syntax:

Record.SETFILTER(Field, String [, Value], ...];

where Field is the name of the field to set a delimitation on. String is a filter
expression that may contain %1, %2 and so on to indicate locations where the
system will insert values (but not operators) given as the Value parameter(s) in
a filter expression.

Here are two examples of using SETFILTER:

Customer.SETFILTER("No.", '>10000 & <> 20000');

This statement would select records where the No. is larger than 10000 and not
equal to 20000.

Customer.SETFILTER("No.",'>%1&<>%2',Value1, Value2);

If the variables V1 and V2 have been assigned ‘10000’ and ‘20000’,

respectively, this statement will have the same effect as the first one.

GETRANGEMIN This function retrieves the minimum value of the delimitation currently in effect
for a field. GETRANGEMIN has this syntax:

Record.GETRANGEMIN(Field);

GETRANGEMIN will cause a run-time error if the filter currently in effect is not a
range. That is, if a filter has been set like this:

Customer.SETFILTER("No.",'10000|20000|30000');

then

BottomValue := Customer.GETRANGEMIN("No.");

will fail, since the filter is not a range.

GETRANGEMAX GETRANGEMAX works like GETRANGEMIN, except that it retrieves the

maximum value of the delimitation currently in effect.

The Essential C/AL Functions 285

 Chapter 14. Using C/AL

Inserting, Modifying and Deleting Records

These function are used to maintain the database by adding, modifying and
removing records.

Generally, these functions return a boolean value that indicates whether they
succeed. If you do not handle the return value in your code, a run-time error
will occur 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 yourself (knowing that the function did not succeed, of
course).

INSERT This function inserts a record in a table, as in this example:

Customer.INIT;
Customer."No." := '4711';
Customer.Name := 'John Doe';
Customer.INSERT;

These statement will insert a new record, with No. and Name having the
assigned values, while other fields will have their default values. Supposing
that No. is the primary key of the Customer table, the record will be inserted in
the Customer table unless there already is a record in the table with the same
primary key. In that case, as the return value is not tested, this error message
would be displayed:

MODIFY This function is used to modify an already-existing record. Like INSERT, it

returns a boolean–TRUE, if the record to be modified exists, FALSE otherwise.

MODIFY is used like this:

Customer.GET('4711');
Customer.Name := 'Richard Roe';
Customer.MODIFY;

The statements above would change the name of customer 4711 to Richard
Roe.

286 The Essential C/AL Functions

 Chapter 14. Using C/AL

MODIFYALL This function is used to do a bulk update of records. MODIFYALL respects 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.

You could use MODIFYALL like this:

Customer.SETRANGE("Salesperson Code",'PS','PS');
Customer.MODIFYALL("Salesperson Code",'JR');

The SETRANGE statement selects the records where Salesperson Code is PS,
and MODIFYALL changes these records to have Salesperson Code set to JR.

DELETE This function is used to delete a record from the database. The record to delete
must be specified (using the value(s) in the primary key fields) before calling
the function. (This means that DELETE does take filters into consideration.)
Here is an example in which DELETE is used to delete the record with customer
number 4711:

Customer."No." := '4711';
Customer.DELETE;

DELETE returns a boolean value: TRUE if the record could be found, FALSE
otherwise. Unless you test this value yourself, a run-time error will occur when
DELETE fails (returns FALSE).

When developing your application, your should consider this scenario:

1 You retrieve a record from the database.

2 You perform various checks to determine whether the record should be

deleted.

3 You delete the record, if step 2 indicated that you should.

Now, this can cause problems if, in a multiuser environment, another user
modifies or deletes the record between 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
seemingly inexplicable 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 (described below)–but

The Essential C/AL Functions 287

 Chapter 14. Using C/AL

LOCKTABLE should be used as sparingly as possible, since this function

effectively short-circuits the concept of optimistic concurrency, thereby
degrading performance.

DELETEALL This function is used to delete all records that are selected by the filter
settings–if no filters are set, all records in the table will be deleted.

The following statements would delete all records where Salesperson Code is
PS from the Customer table:

Customer.SETRANGE("Salesperson Code", 'PS', 'PS');

Customer.DELETEALL;

Transactions
Normally, you do not need to be concerned with transactions and table locking
when developing applications in C/SIDE–Appendix D, C/SIDE in Multiuser
Environments, explains the details.

There are, however, some situations where you will have to lock a table
explicitly. For example, if you, in the beginning of a function, inspect data in a
table, then use this data to perform various checks and calculations and finally
want to write back a record, based upon the result of this processing, you will
want the values that you retrieved at the beginning to be consistent with the
data in the table now–in short: you cannot allow other users to update the
table while your function is busy doing its calculations.

LOCKTABLE The solution is to lock the table yourself, at the beginning of your function, by
using the LOCKTABLE function.

Working with Fields

These functions perform various actions on fields.

CALCFIELDS The CALCFIELDS function is used to update FlowFields. As described in Form

and Control Properties on page 110, FlowFields are automatically updated
when they are direct source expressions of controls, but they must be explicitly
calculated when they are not (that is, are part of a more complicated
expression).

When you use FlowFields in C/AL functions, you have to update them yourself,
and this is what you use the CALCFIELDS function for. In the statements below,

288 The Essential C/AL Functions

 Chapter 14. Using C/AL

the SETRANGE function sets a filter, and then CALCFIELDS is called.

CALCFIELDS will calculate the Balance and Balance Due fields by taking
account of the filter setting and performing the calculations that are defined as
the CalcFormula properties of the FlowFields.

SETRANGE("Date Filter",0D,TODAY);
CALCFIELDS(Balance,"Balance Due");

CALCSUMS The CALCSUMS function is used to calculate the sum of one or more fields that
are SumIndexFields in the record. For CALCSUMS to work, a key that contains
the SumIndexFields must be selected as the current key. Like CALCFIELDS,
CALCSUMS takes the current filter settings into account when performing the
calculation.

In the statements below, an appropriate key is selected. Then filters are set,
and finally the summation is performed.

SETCURRENTKEY("Customer No.")
SETRANGE("Customer No.",'10000','50000');
SETRANGE(Date,0D,TODAY);
CALCSUMS(Amount);

FIELDERROR The FIELDERROR function triggers a run-time error after having displayed a
field-related error message. The function is very similar to the ERROR function,
described on page 295, but is has some benefits. For one thing, it is easier to
use. The more important reason, however, is that 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.

FIELDERROR can be called simply as:

Item.GET('70000');
IF Class <> 'HARDWARE' THEN
FIELDERROR(Class);

This will cause an appropriate message to be displayed, depending on whether

Class currently is empty or has a value.

The Essential C/AL Functions 289

 Chapter 14. Using C/AL

A message like this will appear when a field has a ‘wrong’ value:

You will see a message like this when a text or code field contains the empty
string:

(When a numeric field is empty, it is considered as having the value 0

(zero)–and will produce a message like the first one shown, with ‘0’ instead of
‘FOOD’.)

Finally, you can add your own text if the default texts don’t suit your
application. Then, you call FIELDERROR like this:

IF Class < '4711' THEN

FIELDERROR(Class,'must be greater than 4711');

and the message will look like this:

FIELDNAME The FIELDNAME function returns the name of a field. Again, you could simply
use the name, as you probably know it when you are writing the code, but by
using FIELDNAME, you can create messages that will still be meaningful if the

290 The Essential C/AL Functions

 Chapter 14. Using C/AL

field name is later changed. FIELDNAME could be used together with

FIELDERROR, in a construction like this:

FIELDERROR(
Quantity,'must not be less than ' +
FIELDNAME("Quantity Shipped"));

INIT The INIT function initializes a record. If a default value for a field has been
defined (by the InitValue property), this value will be used for the
initialization–otherwise, there is a default value for each data type (see the
online C/SIDE Reference Guide entry for INIT).

Note that INIT does not initialize the fields of the primary key.

TESTFIELD This function is used to test a field against a value. If the test fails, that is if the
values are not the same, an error message is displayed, and a run-time error is
triggered, meaning that any changes made to the record will be discarded. If
the value to test against is the empty string, the field has to have a value other
than blank or 0 (zero).

The following statements

Code := 'DK'
TESTFIELD(Code,'ZX');

would give this error message:

VALIDATE The VALIDATE function is used to call the OnValidate trigger of a field, as in this
example, where it will call the OnValidate trigger of the Total Amount field:

VALIDATE("Total Amount");

The function is useful for centralizing processing–thus making your application

easier to maintain. Suppose that the OnValidate trigger of the Total Amount
field performs a calculation with values from three other fields as operands.

If the contents of any of these fields changes, the calculation must be

performed. You should avoid entering the calculation formula in the

The Essential C/AL Functions 291

 Chapter 14. Using C/AL

OnValidate triggers of each field–there will be all sorts of possibilities for

errors if the calculation formula later has to be changed.

Instead, you should perform the calculation in the OnValidate trigger in only
one of the fields and call this trigger code from the OnValidate triggers of the
other fields.

User Messages And Dialogs

There are several specialized functions available for displaying messages and
gathering input–but generally, you should use forms whenever it is possible.
When you use forms, your application will have a much more consistent user
interface.

There are, however, situations where it is reasonable to use the dialog

functions. The two most important uses are to display a window that indicates
the progress of some processing that may take a long time and to halt
execution (in order to display an error message or get the user to confirm a
choice before the program continues execution). You will also find the
STRMENU function useful for creating forms to present options to the user–it is
much faster to use this function than to design a form solely to present a
limited set of options to the user.

Creating a Window to Indicate Progress

When you have written an application where some processing may–for
perfectly good reasons–take a long time, you should consider displaying a
window that informs the user of the progress that is being made. The
information itself may be superfluous, but it is a good idea to indicate to the
user that something is actually going on and the program is still running.

Using a dialog window will also give the user an opportunity to stop the
processing–a Cancel button is automatically part of a dialog window.

292 The Essential C/AL Functions

Chapter 14. Using C/AL

In some applications, you can create an indicator control to do this. How to do

it is described in the section Using an Indicator to Display Values on page 136.
In other applications, you can create a window like this instead:

The idea is that each field is updated while the program is running. In the
example here, the fields are used to count the number of postings being made.
In another situation you could display, for example, the number of the account
that is currently being processed, like this

To create a window like this, follow these steps:

1 Declare a variable of type Dialog:

2 Open the dialog window, and define the string that will be displayed:

ProgressWindow.OPEN('Processing account number #1#######');

The Essential C/AL Functions 293

 Chapter 14. Using C/AL

The part of the string that contains pound signs (#) and a number defines a
field that will be displayed in the window, and the number (‘1’ in this
example) can be used to refer to the field.
3 You can display the value of any variable in the field. In the example below,
the number of each account will be displayed as it is processed:

REPEAT
ProgressWindow.UPDATE(1,ChartOfAcc."No.");
// process the account...
UNTIL ChartOfAcc.NEXT = 0;

4 Finally, close the window when you are done using it

ProgressWindow.CLOSE;

Other User Messages

There are a number of other dialog functions available for displaying short user
messages. A common trait of these dialogs–except MESSAGE–is that execution
stops until the user makes a response.

MESSAGE The MESSAGE function displays a message in a window that remains open
until the user clicks the OK button on the window. Note that MESSAGE
executes asynchronously, that is: 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, as in this example:

The window was created by this statement:

MESSAGE(
'Quote %1 has been changed to order %2.',
"No.",SalesOrderHeader."No.");

294 The Essential C/AL Functions

 Chapter 14. Using C/AL

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
unlike in the example of the progress indication windows, the MESSAGE
function was used without first declaring a variable of type Dialog, since there
will be no need to refer to this window again.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ERROR The ERROR function is very similar to the MESSAGE function, except for one
detail: when the user has acknowledged the message, execution ends. See
also the description of FIELDERROR on page 289.

CONFIRM The CONFIRM function is used is display a message, just like MESSAGE: but
unlike MESSAGE, this function returns a value that can (and must) be used,
depending on whether the user chooses Yes or No. Its obvious use is for asking
a question like this:

The window was created by this statement:

IF CONFIRM('Do you want to convert the quote to an order?',FALSE) THEN

.... // do the conversion
ELSE
EXIT;

The FALSE parameter means that the negative answer (No) will be the default.

A Quick Options Form

The STRMENU function is used to create and display a form with an option
group, and to return the user selection to the program.

STRMENU has this syntax:

OptionNumber := STRMENU(OptionString [, DefaultNumber]);

where OptionNumber is the number of the option the user chooses. The first
option in the 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

The Essential C/AL Functions 295

Chapter 14. Using C/AL

default option (if DefaultNumber is not defined, the system will use option
number 1 as the default.)

The statement

Selection := STRMENU('Save,Close,Cancel',3);

will create this:

Notice that the Cancel option is the default–as the DefaultNumber parameter
was set to 3. It is a good idea to let the default option be a ‘harmless’
action–like Cancel–as this option can be chosen by pressing Enter. If the user
inadvertently presses Enter, no catastrophes will happen, which they might,
if, for example, one of the options was ‘Delete all’.

296 The Essential C/AL Functions

Chapter 15
C/AL Debugging

This chapter describes the nature of program

errors–bugs–and how to use the C/AL debugger
to track down errors.

· What Are Bugs?

· Syntax Errors
· Run-Time Errors
· Program Logic Errors
· The C/SIDE Debugger
 Chapter 15. C/AL Debugging

15.1 What Are Bugs?

There are three categories of errors you can meet when you develop
applications that use C/AL code

· Syntax errors
· Run-time errors
· Program logic errors
Traditionally, errors in computer programs are called bugs (as they can be just
as annoying), and the process of finding and correcting errors is, correspond-
ingly, called debugging.

This chapter describes how you can find and eliminate bugs and errors, and it
shows how you use the C/AL debugger to find run-time and program logic
errors.

298 What Are Bugs?

 Chapter 15. C/AL Debugging

15.2 Syntax Errors

These errors are detected by the C/AL compiler when you try to compile C/AL
code, be it in a codeunit or as code in another object (table, form, report). The
compiler will notify you of the error with a message like this

or this

When you have pressed Enter and acknowledged the error message, the C/AL
editor will appear with the cursor in front of the offending expression. Note
that the error message may not always reflect the nature of the error. Consider
this message:

Syntax Errors 299

Chapter 15. C/AL Debugging

When you look at the offending code in the editor, if becomes clear that the
error has nothing to do with an unknown variable:

The real error is a misspelling of IF, which has been entered as UF. From the
point of view of the compiler, UF is an unknown identifier, and hence the error
message. When you look at the code, however, it is easy to see what was really
the matter.

The compiler will not compile code that contains any syntax errors, like a
missing THEN in an IF statement, or code that uses undeclared variables.

300 Syntax Errors

 Chapter 15. C/AL Debugging

15.3 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 in these
cases. A good example is division by zero. Consider this statement

Ratio := First_number / Second_number;

There is nothing wrong with the syntax–but the statement may cause the
following error:

This error occurs because the Second_number variable has been assigned a
value of 0 (zero), thereby causing a division by zero.

If all three variables are of type integer, the following error could occur:

This error occurs because the result of the division cannot be contained in an
integer. Therefore, the result is converted to decimal–but then the conversion
back to integer (in order to fit the result into the Ratio variable) fails.

The common trait of these errors is that the code can work perfectly in many
situations–and then fail in some. The real danger 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, the default messages
shown above will appear. If, as in the example, the division by zero was

Run-Time Errors 301

Chapter 15. C/AL Debugging

attempted using three variables that were assigned values in a simple form,
like this:

and the form was designed like this:

and, finally, the expression

Ratio := First_number / Second_number;

in the OnValidate trigger of the Second_number text box, then, after the user
has acknowledged the run-time error by clicking OK, the form will look like
this:

302 Run-Time Errors

 Chapter 15. C/AL Debugging

At this point the user cannot move out of the text box where Second_number is
to be entered, or close the form, without changing the value to something
other than 0 (zero).

About Run-Time Errors and Data Consistency

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
At this point, you may wonder if run-time errors could compromise the integrity
of the database–for example, if some fields are updated in a trigger and a run-
time error occurs while some other fields have not updated.
Appendix D, C/SIDE in Multiuser Environments, explains how data integrity is
always maintained, under all circumstances. When a trigger is entered, a write
transaction is begun. If a run-time error occurs inside the trigger, the write
transaction will be rolled back and the execution of the trigger terminated.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

How to Avoid Run-time Errors

Basically, run-time errors should never occur, and they do not have to,
provided that you exercise care when programming. The description below
gives some guidelines on how to avoid run-time errors, but they are only
guidelines, as the conditions under which run-time errors occur are highly
dependent on the context of your application. If, for example, you use the GET
function to locate a record, you will have to handle the possibility that a run-
time error will occur if there are situations where no record will be found. On
the other hand, if you are absolutely 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.)

Run-time errors can roughly be put in two categories: those errors that are
related to the use of data types, and those that occur if a function does not
succeed in doing what it is supposed to do. Division by zero does not fit readily
into either of these categories, but it has been placed in the first one.

The heading of this section is, perhaps, overly optimistic: you can only prevent
some (mainly the data-type-related) errors from occurring at all. Other errors
cannot always be avoided, but you can write code that shields the user from
the error. That is, instead of the default error handling (which amounts to
displaying a message, closing the form that was active when the error occurred
and rolling back any changes to the database), you can write a better error
handler that, for example, gives the user a chance to correct the input that

Run-Time Errors 303

 Chapter 15. C/AL Debugging

caused the error, or, at least, displays a message that explains in further detail
why the error occurred.

Data-Type-Related Errors
The most important thing to do to avoid this category of run-time errors is to
use correct data types. Errors like the type conversion error on page 301–and
overflow errors–can be avoided by using the correct data types. In the context
of the example, integer was obviously not a good choice for the Ratio variable.
See Introducing the C/AL Data Types on page 252 for a description of the data
types, and appendix B for a description of how type conversion takes place in
C/SIDE.

The division by zero error on page 301 could have been 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 never should be allowed

to have a value of 0 (zero), the best place to perform this check is in the
OnValidate trigger of the field. In this way, a value of 0 (zero) could never be
entered in the field, no matter how many different text boxes are used to enter
data in the field.

Other Run-Time Errors

Any function that can fail to accomplish what it is intended to do can cause a
run-time error. A good example is the GET function, used to locate a record in a
table according to specified criteria. Consult the online C/SIDE Reference
Guide for the GET function, and observe the syntax of the command

[Ok :=] Record.GET([Value1], [Value2 ],...)

The return value of the function is Ok–a boolean. If a record is found, Ok will be
TRUE, otherwise it will be FALSE. This return value can be ignored, as indicated
by the square parentheses. If it is ignored, and the requested record cannot be
found, a run-time error will occur and a system-generated error message will

304 Run-Time Errors

 Chapter 15. C/AL Debugging

be displayed. If, on the other hand, you test the return value, a run-time error
will not occur, as it is then assumed that you handle the condition yourself.

The online C/SIDE Reference Guide always describes whether a function

handles errors in a way similar to GET. You can also look at the syntax
description in the Symbol Menu, to see if the function you intend to use returns
a value called Ok. If it does, you should consult the online C/SIDE Reference
Guide as there are some functions that return a boolean for other reasons than
those described here. For example, the ASCENDING function can be used to
check the sorting order of a table, and in this case it will return TRUE if the
sorting order is ascending, and FALSE if it is descending.

Example

By using the return value, in a construction like this:

IF NOT Customer.GET("No.") THEN

Customer.INIT;

or like this

IF NOT Customer.GET("No.") THEN

BEGIN
MESSAGE('Customer %1 not found', "No.");
EXIT;
END;

you can shield the user from a run-time error. In the first example, if a Customer record with the
given No. cannot be retrieved, an (empty) record is initialized. In the second example, the user is
notified that a record cannot be found and the trigger from where the GET function was called is
exited.

You should only take the examples above as general guidelines–you will have to consider how to
handle situations like these in the context of your own application.

Finding and Correcting Run-Time Errors

As you can see from the run-time error messages reproduced on page 301, this
type of message is supposed to be read by the end user. Therefore, the
messages do not include references to variables or functions, but rather an
explanation and the ‘real’ values that caused the error. This means that these
errors can be a little harder to locate than, for example, syntax errors.

In order to track down a run-time error, you will need an exact description of
the sequence of events that led to the error: that is, what the user was doing at

Run-Time Errors 305

Chapter 15. C/AL Debugging

the time of the error, and what values the user had entered or what record
caused the error.

If the error was caused by something as simple as a calculation formula 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 quite easily. If, on the
other hand, the circumstances that led to the error are more complicated, and
you cannot pinpoint the exact place directly, you can use the debugger as
described in Using the Debugger to Track Down Errors on page 315.

306 Run-Time Errors

 Chapter 15. C/AL Debugging

15.4 Program Logic Errors

The third major category of errors is the program logic errors (strictly speaking,
the term bug should perhaps be reserved for errors of this type). A program
logic error is an error in an application that could perfectly well be compiled,
that can be run without causing run-time errors, but that fails to function as
was intended.

In can be argued that many, if not most, run-time errors are also program logic
errors. However, the ‘true’ program logic error will not make it itself noticed in
a similarly spectacular way but will quietly generate erroneous data–that may
not always be detected straight away.

The following example illustrates what a program logic error is.

In an application, sales orders are entered on a main form/subform: the

general information is entered in the sales header table from the main form,
and specific information about items that are ordered is entered in the sales
line table from the subform. During data entry, a form that shows statistics
about the current order can be displayed. When the form is called, a series of
calculations take place and the resulting information is shown like this:

When the form is run with sample data, something appears to be wrong. When
compared with the sales order entry forms, the Quantity on the sales statistics
form seems to be incorrectly calculated.

Program Logic Errors 307

Chapter 15. C/AL Debugging

The sum of the quantities for those two sales lines that are visible in the
subform alone is 4 (and there are several lines below those two lines).

The numbers that are shown in the sales statistics form are calculated in the
OnAfterGetRecord trigger of the form, like this:

The erroneous statement is highlighted. Instead of adding the quantity from

each sales line in the REPEAT loop to the variable LineQty (the source
expression of the Quantity text box), the variable is assigned the quantity on
the current sales line in each iteration. The values that is finally displayed is
simply the quantity on the last of the sales lines.

In this example, the error was easy enough to find, just by looking at the C/AL
code. Using the Debugger to Track Down Errors on page 315 shows how the

308 Program Logic Errors

Chapter 15. C/AL Debugging

debugger can be used to find the error. In a more complex application, this will
be, if not the only way, then the fastest.

Program Logic Errors 309

 Chapter 15. C/AL Debugging

15.5 The C/SIDE Debugger

The C/SIDE debugger is used to locate run-time errors and program-logic
errors. The debugger will let you execute your C/AL one statement at a time
and inspect the contents of global and local variables at each step.

If you are trying to track down a run-time error, stepping through the code will
help locate the problematic statement easily, as you can step through the
statements until you arrive at the statement that causes the error.

You can also use the debugger to find a logical error, but finding the error will
not be as easy, and you must have a good understanding of how the code is
supposed to work. If you know what the code should do, then you can use the
possibilities for inspecting the variables at various stages of execution to find
out where the values that are actually used differ from the values you expected
when you designed the application.

The Debugger and the Command Buffer

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Appendix E, Performance, explains how C/SIDE uses a command buffer to
improve performance. When the debugger is used, however, the command
buffer is deactivated. The appendix describes what this means, and how it can
lead to some confusion when using the debugger.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Operating the Debugger

To use the debugger, toggle Active on in the Debugger submenu of the Tools
menu. Leave the setting of Breakpoints on Triggers at its default (on). When
you start running for example a form, the debugger will now be in charge and
interrupt execution when the first trigger is entered. You will see a screen like
this:

310 The C/SIDE Debugger

 Chapter 15. C/AL Debugging

The screen resembles the screen in the C/AL editor, but there are some
differences. You can move around with the usual navigation keys and the scroll
bars, and you can put the focus on a statement by clicking on it, but you cannot
edit the code. The column at the far left is used to show the statement that will
be executed next. The indicator is the t. The second column to the left of the
statements contains only bullets in the picture above. It can, however, contain
three different symbols, like this:

Symbol Meaning
There is a disabled breakpoint at this statement.
This is a statement that will be executed.
There is an active breakpoint at this statement.

What Is a Breakpoint?
The basic concept in debugging is the breakpoint. A breakpoint is a mark that
you can set on a statement. When the program flow reaches the statement, the
debugger will intervene and suspend execution until you instruct it to go on.
Without any breakpoints, the code would just run normally when the debugger
is active.

It was mentioned above that you must leave the Breakpoint on Triggers option
on when you activate the debugger. The reason is obvious: if you do not, the
code will be executed normally, since there are no breakpoints. If, however,
the Breakpoint on Triggers option in on, then execution will be suspended
when the first trigger is entered. At this point you can set other breakpoints
and set the Breakpoint on Triggers option to off, if you want.

The C/SIDE Debugger 311

 Chapter 15. C/AL Debugging

Setting Breakpoints
Breakpoints are set and cleared by using the Toggle Breakpoint command from
the Run menu (the Run menu is only available while execution is suspended).
Actually, the command is a three-way toggle, corresponding to the three
different breakpoint symbols that can appear in front of a statement (see
above). When Toggle Breakpoint is used, the state will change according to
this sequence:

no breakpoint -> breakpoint -> disabled breakpoint -> no

breakpoint

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).

All breakpoints can be removed at once by using the Clear All Breakpoints
command from the Run menu.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Breakpoint On Triggers is set independently of other breakpoints–so Clear All
Breakpoints will not affect Breakpoint on Triggers.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Controlling Execution in the Debugger

When the execution of an application has been suspended by the debugger,
you can control how to resume execution. You have three commands at your
disposal: Continue, Step Into and Step Over–all available from the Run menu:
t

312 The C/SIDE Debugger

 Chapter 15. C/AL Debugging

The three commands work like this:

Command Meaning
Continue Execution will be resumed and continue till the next breakpoint.
Step Into Statements will be executed one at a time, and you have the opportunity to decide
how to continue after each statement, and the execution will step into any function
that is called. To step into means that the debugger will single-step through the
statements in the function that is called.
Step Over Statements will be executed one at a time, like Step Into, but any called function
will not be stepped into. The functions that are called will be executed completely
before the next statement of the calling function is executed.

Example

The difference between Step Into and Step Over can be seen from an example like. The following is
the C/AL statement about to be executed:

Result := FunctionLib.CalculateResult(a,b,c);

If Step Into is used now, the debugger will open the codeunit (FunctionLib) that contains the
CalculateResult function and the first statement of this function will be the next statement at which
the debugger will stop. If, on the other hand, Step Over is used, FunctionLib.CalculateResult will
simply be executed, and the debugger will next stop at the statement that follows the statement
above.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
if Breakpoint on Triggers is on, execution will be suspended at every trigger
that is entered, even when Step Over is used.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Examining Variables, Filters and Keys

While execution is suspended, you can examine the current values of local and
global variables, the table filters that are currently used, and the key (sorting
order) of tables.

In order to examine the variables:

1 Choose C/AL Globals from the View menu while execution is suspended to
examine the global variables, or choose C/AL Locals to examine the local
variables of a function.

The C/SIDE Debugger 313

Chapter 15. C/AL Debugging

2 To see all fields of a record, choose Zoom from the Record menu of the
Globals (or Locals) form while the focus is on the record. Click on records to
move the focus.

3 To examine the filters currently in use, choose Table Filter from the Record
menu while the focus is on the record you want to investigate.

314 The C/SIDE Debugger

 Chapter 15. C/AL Debugging

4 To see what sorting order is in use, choose Sorting from the Record menu
while the focus is on the record you want to investigate.

Using the Debugger to Track Down Errors

The primary use of the debugger is to track down program logic errors. The
debugger is also useful when you are trying to locate the statement that
caused a run-time error, especially when it is a non-trivial error.

Locating a Run-Time Error

The example here is very simple and artificial. It shows that some run-time
errors are in reality program logic errors. Here, the program-logic error leads to
a division by zero. (It might be claimed that it is preferable to have logical
errors end by causing run-time errors, because then they will at least be
recognized as errors.)

The user sees this message:

when running a form that displays statistics about sales orders–but only sees
it for some orders. The form is only informational, so the user does not enter
any data and cannot point to what exact conditions cause the error. Even if the

The C/SIDE Debugger 315

Chapter 15. C/AL Debugging

user can identify sales orders that will cause the error to occur, it would be
cumbersome to try and find differences between such orders and other orders.

To find the error, follow these steps:

1 Run the form with the same data as the user, until an order that provokes
the error has been identified.

2 The form will close after the error. Open it again, and turn the debugger on
by choosing Active from the Debugger submenu of the Tools menu. Make
sure that Breakpoint on Triggers is on (there will be a check mark next to the
menu item when it is).

3 Step through the C/AL code statement by statement by using Step Into until
the error occurs, thereby identifying the statement that causes the run-time
error.

In the example here, division by zero happens when the statement with the t
mark is executed:

Examining the statement that causes the error makes it clear what the error is.
After testing that AmountLCY is 0 (zero), the variable is used as the
denominator in a division. This ensures that when a customer record is found
where AmountLCY is in fact 0 (zero), the division by zero will occur. The
intention was, however, this:

IF AmountLCY <> 0 THEN

ProfitPct := ROUND(100 * ProfitLCY / AmountLCY,0.1);

that is, to perform the division only when AmountLCY is not 0 (zero).

316 The C/SIDE Debugger

 Chapter 15. C/AL Debugging

Finding a Program Logic Error

Although the error described in Program Logic Errors on page 307 could be
found be looking closer at the C/AL code, the debugger could also have been
used to pinpoint the erroneous statement.

To find the error, follow these steps:

1 Go to the point in the program just before the form with the error is opened,
and turn the debugger on by choosing Active from the Debugger submenu
of the Tools menu. Make sure that Breakpoint on Triggers is on (there will
be a check mark next to the menu item when it is).

2 Open the form where you suspect that there is an error. In the example here,
it is the Sales Statistics form.

As you can see, the debugger has suspended execution on entering the first
trigger of the Statistics form.

3 Open the global variable window by choosing C/AL Globals from the View
menu, and arrange the windows so you can see both the debugger window
and the global variable window.

The C/SIDE Debugger 317

Chapter 15. C/AL Debugging

4 Use Step Into to step through the statements, and observe the variables. In
the example here, the interesting part is when the REPEAT loop is entered
and iterated. After stepping through the loop once, the global variable
window looks like this:

318 The C/SIDE Debugger

Chapter 15. C/AL Debugging

5 Step through the loop once more, and look at the variables:

When you look at the values of the variables, it becomes clear that while the
values of most of the variables have changed, some have not. A number of the
variables have a value of 0 (zero), just as after the first iteration. Inspecting the
code will reveal that this was to be expected in the context. LineQty, the
variable that is the source expression of the Quantity text box, remains at a
value of 2, although every item should have had at least a quantity of 1 (so
LineQty should at least be 3).

The conclusion must be that for some reason, the quantity is not summed as
the loop is repeated. In this limited example, the offending statement is easy to
find, as described in Program Logic Errors on page 307, but you would use a
similar strategy to find logical errors in a larger and more complex application.

The C/SIDE Debugger 319

Chapter 15. C/AL Debugging

320 The C/SIDE Debugger

Part 6
Appendixes
Appendix A
C/SIDE Specifications

This appendix provides the technical

specifications of C/SIDE. Use this information to
get an overview of maximum sizes and other
limitations that may affect your application
design.

· Specifications for the DBMS

· Specifications for C/SIDE Application Objects
.

15.6 Specifications for the DBMS

These are the specifications for the C/SIDE DBMS (Database
Management System).

Maximum number of physical disk files 16

Database file size 16 x 2 GB

Maximum number of objects in a database Infinite

Maximum number of characters in application object 30

names

Maximum number of characters in a password 10

Maximum number of concurrent users 500

(the actual limit depends on your hardware and the
workload)

Maximum cache size 1000 MB

324
 15.7 Specifications for C/SIDE Application Objects

15.7 Specifications for C/SIDE Application Objects

This section lists specifications for the five types of application
objects in a C/SIDE database.

Specifications for Tables

Range for table object ID numbers 1 -999,999,999 (A)

Maximum number of characters in a table name 30

Maximum table size Infinite

Maximum number of records in a table Infinite

Maximum record size 2000

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 + 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 250

code field

Maximum size of a BLOB field 2 GB

Maximum number of characters in a field name 30

325
.

(A) all 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. Please contact your NTR for more
information.

Specifications for Forms and Reports

Range for form or report object ID numbers 1 - 999,999,999 (A)

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

(A) all 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. Please contact your NTR for more
information.

Specifications for Codeunits

Range for table object ID numbers 1 - 999,999,999 (A)

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

326
 15.7 Specifications for C/SIDE Application Objects

Maximum physical size of a codeunit 2 GB

Lower bound of index in an array 1

(A) all 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. Please contact your NTR for more
information.

327
.

328
Appendix B
Type Conversion

This appendix describes all possible type

conversions in C/AL expressions. The appendix
is divided into the following sections:

· Type Conversion in Expressions

· Type Conversion Mechanisms
· Relational Operators
· Boolean (Logical) Operators
· Arithmetic Operators
.

15.6 Type Conversion in Expressions

Consider the following statements

CharVar := 15; // A char variable

integerVar := 56000; // An integer variable
Sum := CharVar + integerVar;

The last statement involves one or two type conversions. The right-
hand side of the 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. But if the type of the left-hand side
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 (this kind of conversion is discussed in
Assignment and Type Conversion on page 262.)

This appendix describes the type conversions which sometimes

take place when expressions are evaluated. First, some general
rules:

· 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’, as defined
below.

328
 15.6 Type Conversion in Expressions

decimal is the most

general numeric data
Numbers
type decimal
integer, option

char
char is the least
general numeric
data type

Strings
The text data type is text
more general than code
the code data type

· The most general data types include all possible values from
the less general data types: a decimal is more general than an
integer, which again 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 some examples.

Example 1

Evaluation of a numeric expression:

integer + decimal

This expression contains two sub-expressions of different type. In order to

add these, the system will convert the left-hand side sub-expression to
decimal:

decimal + decimal

When the left-hand side sub-expression has been converted, the expression
can be evaluated, and the resulting data type will be decimal:

decimal + decimal ⇒ decimal

329
.

Example 2

Evaluation of a string expression:

text + code

This expression contains two sub-expressions to be concatenated. In order

to do this, the system will convert the sub-expression of the least general
data type (code) to the most general data type (text).

text + text

When the right-hand side argument has been converted, the expression can
be evaluated, and the resulting data type will be text.

text + text ⇒ text

330
 15.7 Type Conversion Mechanisms

15.7 Type Conversion Mechanisms

This section discusses the type conversion mechanisms for the
C/AL operators in more depth. The starting point is to divide the
operators into some main categories:

· Relational operators
· Logical operators
· Arithmetic operators
The following subsections discuss 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.

The relational operators will be treated first, as they are common

to most of the C/AL data types.

Relational Operators
The relational operators are used to compare expressions. The
table below defines the evaluation rules for relational operators.
The rules assume that the data types of the expressions can be
compared–refer to Valid Uses of Relational Operators below for a
complete overview of comparable data types.

Operator Operator Name Expression Resulting Data

Type

> Greater than Expr > Expr boolean

< Less than 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

331
.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
when using relational operators, upper and lower case 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.

From the table you can see that a valid use of the relational
operators is, for example, text compared with text or code, while
boolean cannot be compared with anything else than boolean, and
so forth.

Relation
al
boolean

decimal
integer
option

Operator
code
date

time
char

text

boolean boolea - - - - - - - -
n

char - boolea boolea boolea boolea - - - -

n n n n

option - boolea boolea boolea boolea - - - -

n n n n

integer - boolea boolea boolea boolea - - - -

n n n n

332
 15.7 Type Conversion Mechanisms

Relation
al

boolean

decimal
integer
option
Operator

code
date

time
char

text
s

decimal - boolea boolea boolea boolea - - - -

n n n n

date - - - - - boolea - - -
n

time - - - - - - boolea - -
n

text - - - - - - - boolea boolea

n n

code - - - - - - - boolea boolea

n n

Boolean (Logical) Operators

The logical operators can only be used with arguments that can be
evaluated to boolean.

Operator Name Expression Resulting Data

Type

NOT Logical negation NOT boolean boolean

AND Logical and boolean AND boolean

boolean

OR Logical or boolean OR boolean

boolean

XOR Exclusive logical or boolean XOR boolean

boolean

As the above shows, the NOT operator is a unary prefix operator;

that is, it takes only one argument and is placed in front of the
argument. The AND, OR and XOR operators, on the other hand, are

333
.

binary infix operators; that is, they take two arguments and are
placed between the corresponding arguments.

Arithmetic Operators
Here are some examples of how to use the type conversion rules
for arithmetic operators. The examples illustrate how the
operators are supposed to be used and the effect of the type
conversion made automatically by the C/AL compiler. The
examples have been divided into groups corresponding to the data
types in C/AL.

For a full description of the type conversion rules in C/AL, refer to

the tables in the section Complete Overview of Type Conversion
Rules on page 335, which provide a full description of all possible
uses of C/AL operators and the resulting data types.

Example

The table below illustrates type conversion in integer operator expressions

Operator Name Expression Resulting Data

Type

+ Unary plus + integer integer

- Unary minus - integer integer

+ Addition integer + integer integer

- Subtraction integer - integer integer

* Multiplication integer * integer integer

/ Division integer / integer decimal

DIV Integer division integer DIV integer integer

MOD Modulus integer MOD integer integer

Note that the same rules apply to option operator expressions as well.

334
 15.7 Type Conversion Mechanisms

Example

This table illustrates type conversion in decimal operator expressions:

Operator Name Expression Resulting

Data Type

+ Unary plus + decimal decimal

- Unary minus - decimal decimal

+ Addition decimal + decimal decimal

- Subtraction decimal - decimal decimal

* Multiplication decimal * decimal decimal

/ Division decimal / decimal decimal

DIV Integer Division decimal DIV decimal decimal

MOD Modulus decimal MOD decimal decimal

Example

This table illustrates type conversion in date operator expressions:

Operator Name Expression Resulting Data

Type

+ date addition date + Number date

- date subtraction date - Number date

- date difference date - date integer

In the 'date addition' and 'date subtraction' examples above, a run-time

error will occur if date is a closing date or if date is undefined (0D).

Example

This table illustrates type conversion in time operator expressions:

Operator Name Expression Resulting Data

Type

+ time addition time + integer time

335
.

Operator Name Expression Resulting Data

Type

- time difference time - time integer

The time unit is milliseconds. If time is undefined (0T), a run-time error will
occur.

Example

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

Complete Overview of Type Conversion Rules

The following tables provide 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:

PrefixExpression = PrefixOperator Expression

This 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

336
 15.7 Type Conversion Mechanisms

The Binary Arithmetic Operators

This 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:
InfixExpression = LeftExpression InfixOperator
RightExpression

boolean char option integer decimal date time text code

Operator

+ j c c c c c c c c

- j c c c c c c j j

* j c c c c j j j j

/ j c c c c j j j j

DIV j c c c c j j j j

MOD j c c c c j j j j

c Yes, the operator can take at least one operand (left, right or
both) of the given type.
j No, the operator cannot be used with the given type.

The following tables define the valid uses of the binary arithmetic
operators, and the resulting data types.

Definition of Type Conversion Rules for the '+' Operator

boolean

decimal

The ‘+’
integer
option

code
date
time
char

operator
text

boolean - - - - - - - - -

char - integer integer (C) integer decimal (C) - - - -

(C)

option - integer (C) integer (C) integer decimal (C) - - - -

(C)

337
.

boolean

decimal
The ‘+’

integer
option

code
date
time
char
operator

text
integer - integer (C) integer (C) integer decimal (C) - - - -
(C)

decimal - decimal (C) decimal (C) decimal decimal (C) - - - -

(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 decimal has a fractional part.

Definition of Type Conversion Rules for the '-' Operator

boolean

decimal

The ‘-’
integer
option

code
date

time
char

operator
text

boolean - - - - - - - - -

char - integer integer( integer decimal (C) - - - -

C) (C)

option - integer(C) integer integer decimal (C) - - - -

integer - integer(C) integer integer decimal (C) - - - -

(C)
decimal - decimal decimal decimal decimal - - - -
(C) (C) (C)

date - date(A) date(A)( date(A) date (A) (C) integer (A) - - -

(C) C) (C) (D)

time - time(B) time(B)( time(B) time (B) (C) - integer( - -

(C) C) (C) (D) B)

338
 15.7 Type Conversion Mechanisms

boolean

decimal
The ‘-’

integer
option

code
date

time
char
operator

text
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 decimal has a fractional part.

Definition of Type Conversion Rules for the ‘*’ Operator

* char option integer decimal

char integer (C) integer (C) integer (C) decimal (C)

option integer (C) integer (C) integer (C) decimal (C)

integer integer (C) integer (C) integer (C) decimal (C)

decimal decimal (C) decimal (C) decimal (C) decimal (C)

(C) overflow may occur.

Definition of Type Conversion Rules for the ‘/’ Operator

/ char option integer decimal

char decimal decimal decimal decimal

option decimal decimal decimal decimal

integer decimal decimal decimal decimal

decimal decimal decimal decimal decimal

Note that overflow may occur in all cases in the above table.

A run-time error will occur if the right operand is equal to zero (0).

339
.

Definition of Type Conversion Rules for the 'MOD' and 'DIV'

Operators

MOD and char option integer decimal

DIV

char integer integer integer decimal

option integer integer integer decimal

integer integer integer integer decimal

decimal decimal decimal decimal decimal

A run-time error will occur if the right operand is equal to zero (0).

340
Appendix C
SumIndexFields

This appendix describes SumIndexFields™,

which are the basis for the FlowFields in a
C/SIDE application.

· What Is a SumIndexField?
.

15.6 What Is a SumIndexField?

A SumIndexField is a fundamental feature which is the basis of
FlowFields. SumIndexFields permit fast calculation of sums of
numeric columns in tables, even in tables with many thousands of
records.

A SumIndexField is associated with a key; each key can have at

most 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.

The figure below illustrates a table where the Amount field

(column) is defined as a SumIndexField in the AccountNo + 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.

340
 15.6 What Is a SumIndexField?

AccountNo Date Text Amount Accumulated

(SumIndexField) Sum
A table sorted by 50000 100
01-01-96 60100
AccountNo + Date
50000 01-02-96 200 90300
50020 01-04-96 300 210600
50020 01-25-96 400 1000
50040 02-01-96 500 300
1500

A FlowFilter is
used in the =50020
calculation of the
FlowField

300
The same table
50020 01-04-96 300 600
when the FlowFilter
is applied 50020 01-25-96 400 1000

Sum of Amount
column when the 1000 - 300 = 700
filter is applied

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
above figure, the third field in the column, holding 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.

What advantages do SumIndexFields offer? Sums (of columns) can

be quickly calculated and the result displayed in FlowFields. Let us
say 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, a very time-consuming
operation in a database with thousands of records. Here, you
would create a FlowField, define the calculation formula of this

341
.

FlowField to sum the Amount field, and 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 above figure shows a group of
records selected by a FlowFilter field in the AccountNo. 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.

The time used to maintain the accumulated sum for

SumIndexFields is negligible due to a special index structure used
in the DBMS.

342
Appendix D
C/SIDE in Multiuser Environments

This appendix explains how the DBMS handles

data integrity in a multiuser environment. It
describes how the C/SIDE system handles
situations where more than one user or process
try to change the same object.

· Accessing a Database in a Multiuser

Environment
· Write Transactions and Recovery
· Read Consistency and Concurrency
 15.6 Ensuring Data Integrity in a Multiuser Environment

15.6 Ensuring Data Integrity in a Multiuser Environment

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) as illustrated in the figure below:

Interface

The DBMS includes

mechanisms to
ensure the integrity DBMS
of your data

Logical Database

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 means to obtain data integrity are
centered around a few basic concepts:

· write transactions and recovery

· read consistency and concurrency
· table locking
· deadlock detection
· committing updates
These concepts are discussed and explained in the following
sections.

Write Transactions and Recovery

A write transaction in C/SIDE is defined as an atomic unit of work
on the database which is completed either entirely or not at all. In

344
 15.6 Ensuring Data Integrity in a Multiuser Environment

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 facility that is used both in
single- and multiuser environments.

When a transaction has been submitted to the C/SIDE DBMS, the

system is responsible for making sure that:

· all operations of the transaction are completed successfully and

their effect is recorded permanently in the database, or
· the transaction has no effect at all on the database.
The DBMS must prevent some operations of a transaction being
applied to the database while others are not. 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.

· Missing information makes it impossible to complete the
transaction.
· 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 tables are restored to the state
they had before the transaction started.

A typical example of a write transaction is illustrated by a banking

system where $100 must be transferred 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. By
bundling both operations into a single transaction, either none or

345
 15.6 Ensuring Data Integrity in a Multiuser Environment

both of the operations are executed and the data will always be
consistent.

More on Write Transactions

The previous section explained that the database in C/SIDE will be
consistent 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 contain a facility 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 from failures.

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 modifications already made to the
database must be cancelled. In common database systems this is
achieved by so-called rollback recovery, that is, by backing out the
updates of the application program. This backout 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.

346
 15.6 Ensuring Data Integrity in a Multiuser Environment

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. The figure below shows three applications accessing
the same database. Imagine that the first access is made by a
report. The second access is made by a user who inserts new
entries in the database, and the third access is made by a backup
procedure.

Version A B C D
Time

(A)
Three applications Report
accessing different
versions of the
database
Entry

(B)
Backup

In this example, the generation of a report is a time-consuming

process, and while the report is generated, another user enters or
modifies records in the database. As each entry is committed, a
new version of the database is created, but as the report started, a
snapshot of the database was made and the report continues to
work on version A of the database. A third user starts a backup
procedure. When the backup starts, a snapshot of the current
(most recent) version of the database, B, is made, and the backup
works on this version, uninfluenced by new data that the second
user continues to enter in the system. Working with data versions
makes it possible for many users to access the database without
interfering with each other.

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

347
 15.6 Ensuring Data Integrity in a Multiuser Environment

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.

Only when you commit your updates do your modifications
become public. Your newly-committed updates plus the part of the
database which was not modified make up the newest version.

What is a Data Version?

The data in the C/SIDE database is stored in a well known data
structure that resembles a tree. A tree data structure is formed 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.

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

Imagine that the tree structure in your database contains a branch with
customers A, B and C. Furthermore there are 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. As illustrated in the figure
below, the copies will use two free database blocks. You will then modify the
copies, and the system will create a new internal node.

348
 15.6 Ensuring Data Integrity in a Multiuser Environment

Free database blocks

Database
Version 1

A B C Free
Free

Database
Version 2

A B C C1
A1

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 B
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 can run into trouble in this environment. Suppose

Application A is reading data from the latest version, while
generating a very time-consuming report. In the meantime,
Application B begins performing write transactions which consist
of order entries.

349
 15.6 Ensuring Data Integrity in a Multiuser Environment

As order entries are added to the database, newer versions of the

database are created. 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 A becomes the oldest

complete data version. But B 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 A. A run-time error message is
sent to A on its next read operation–“Data version is no longer
valid”–and it is forced to restart the process with the newest
version. But as long as B continues and the space in the database
available for historical versions remains the same, there is little
hope that A will be able to generate the report. (Enlarging the
database could solve the problem.)

What is 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.

While write operations automatically lock a table during updates,

you can explicitly lock a table, even if you are not certain a write
operation will be performed. 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; that is, locking a table does not prevent other users from
gaining read access to the records in the table.

350
 15.6 Ensuring Data Integrity in a Multiuser Environment

A write lock is active until the write transaction is either aborted or

committed. This figure uses pseudo-language syntax to illustrate
the scope of write locks.

.
.
BeginWriteTransaction;
LockTable(TableA) (1)
FindRec(TableA, ...); (2)
The scope of .
write locks .
InsertRec(TableA, ...) (3)
Table A locked

.
InsertRec(TableB, ...); (4)
.
Table B locked

.
.
.
.
EndWriteTransaction (5)
.
.

This illustrates both an explicit lock and an automatic lock. Line (1)
in the write transaction explicitly locks table A. If this explicit lock
were not set on table A, the DBMS would automatically lock this
table when a record is 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 EndWriteTransaction command
is executed in line (5).

What Is Deadlock Detection?

The correct functioning of a multiuser system will depend on the
coordination of the activities. If transaction processes require
write access to several tables at once, care must be taken to avoid
the situation where one transaction process can obtain access to
some of the necessary tables and another can obtain others of
them, but neither of them can proceed without the other having
finished. This causes each transaction process to wait for the other
to finish. As a result both processes will have to wait forever. Such
a situation is known as a Deadlock (or as Deadly Embrace).

351
 15.6 Ensuring Data Integrity in a Multiuser Environment

In order to avoid deadlock situations, the DBMS has been provided

with an automatic deadlock detection mechanism, which detects
these situations and ejects one of the write transactions. The next
figure illustrates how a deadlock situation can arise.

Application 1 Application 2
AA AA
AA AA
AA
AA AA

Time
AA AA
AA
AA AA
AA AA
AA
AA
AA AA
AA
AA
AA
LockTable(A) AA
AA
AA
AA
AA
AA
AA
AA
AA
Table A now Locked
AA
AA
AA
AA
AA
LockTable(B)
AA
AA
AA
AA
AA
AA
Table BAAnow locked
AA
AA
LockTable(B) AA
AA
AA
AA
AA
AA
AA
AA
AA
Wait for table B to AA

be unlocked LockTable(A)
AA
AA
AA
AA
AA
AA
AA
AA
Wait for table A to
AA
AA
AA
AA
AA
AA
AA
be unlocked
AA
AA AA
AA
AA AA
AA AA
AA
AA AA
AA
AA AA

The automatic deadlock

detection ejects one of The DBMS detects a deadlock situation, and
the applications ejects application 2.

AA
AA
AA AA
AA AA
AA
AA AA
AA
AA AA
AA
AA
AA
AA
AA
AA
AA
Application 2 ejected
AA
AA
AA
AA
AA
and transaction aborted.
AA
AA
AA
AA
AA
Lock attempt on Table A
AA
AA
AA
AA cancelled and Table B
AA
AA
AA
AA
AA
AA
AA
automatically unlocked
AA
AA
AA
AA

Table B locked
AA
AA
AA
AA
AA
AA
AA
AA
AA
AA
AA
AA
AA

The DBMS will always eject the application which causes the
deadlock to occur–as in the example above. This rule applies for
any number of applications involved in a deadlock.

352
 15.6 Ensuring Data Integrity in a Multiuser Environment

Are There Any 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 (the toolkit that
makes it possible to develop applications in the C programming
language that access a C/SIDE database), there are some minor
differences. This subsection explains these differences in detail.

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 perform updates to a C/SIDE

database, these BeginWriteTransaction and EndWriteTransaction
statements are handled implicitly by the system. That is, the
system automatically executes these commands before the C/AL
code is entered and after the C/AL code has been 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 by the system. If, however, you need to perform
more than one write transaction, you have to use COMMIT() in
order to separate the transactions.

The next figure illustrates these differences.

353
 15.6 Ensuring Data Integrity in a Multiuser Environment

Differences in
committing updates
in C/AL and C code
C/AL code C code

BeginWriteTransaction
DBL_BWT();
C/AL Module

C/AL Statements } 1. Trans. C code

DBL_EWT();
} 1. Trans.

Commit(...)

C/AL Statements
} 2. Trans.
DBL_BWT();
C code
} 2. Trans.

EndWriteTransaction DBL_EWT();

The C/AL code contains two write transactions. As the execution of

the C/AL code begins, write transactions are automatically
enabled. By issuing the command COMMIT(), 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 has been
completed, the system automatically ends the second write
transaction. When you use C code to perfom the same
transactions, each transaction must explicitly be encapsulated by
DBL_BWT() and DBL_EWT() commands.

354
Appendix E
Performance

This appendix covers features built into C/SIDE

to increase performance, such as the DBMS
cache, the commit cache and the command
buffer.

· The DBMS Cache

· The Commit Cache
· The Command Buffer
.

15.6 The DBMS Cache

The DBMS cache is a buffer storage that holds copies of portions
of the database that currently is being used by the DBMS. As long
as required data is in cache, data appears to be immediately
available. When required data is not in the cache, it must first be
brought in from the disk.

The DBMS cache is transparent to the user:

· Data is brought into cache automatically and copied back to the

physical disk automatically if modified.
· No instructions are required to do these transfers.
The user does not have to know of the existence of the cache for an
application to work correctly, but the developer has to be aware of
the cache for the application to work well.

The figure below illustrates applications sending requests to the

DBMS. When, for example, Application 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 must be
fetched from a disk.

356
 15.6 The DBMS Cache

Application 1 Application 2 Application 3

Network

DBMS
DB Request Handler

The DBMS cache Cache

Database

: Data flow

At the same time, another application could be modifying a record

in a table in the database. This modification will be written to the
DBMS cache, not to the disk. When this application ends the write
transaction (commits the changes), the data in the cache that was
modified during the transaction will be written to the disk; the
cache is said to be flushed.

The DBMS cache always holds the most-recently-used data. The

cache is continually updated with the relevant data from the
database.

The size of the cache has great impact on the performance. Two
simple rules apply when setting the size of the cache:

· The more memory you assign to the cache, the more efficient it
will be. (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 should not exceed the amount of physical
memory available on your system, as this may cause the

357
.

operating system to swap the cache memory in and out from

disk. This will slow down the overall speed of the C/SIDE system
tremendously.
Refer to C/SIDE Specifications on page 323 for information about
the maximum cache size.

358
 15.7 The Commit Cache

15.7 The Commit Cache

The commit cache is a special write buffer for the disk(s) in the
system. The commit cache has been designed to:

· quickly absorb committed transaction from the DBMS. 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 always is consistent.
The commit cache is placed between the DBMS and the database
and absorbs committed transactions from the DBMS. When the
commit cache has received a committed transaction, it takes care
of writing the data to the disk(s). In this way the DBMS is free to
perform other tasks while data is being written to the disk. The
data is said to be written asynchronously to the disk, as the point-
in-time of the disk write is not synchronous with the point-in-the
time that the transaction was committed by the DBMS.

As described in the section The Physical and the Logical Database

on page 11, the logical database can be stored in several distinct
disk files (which can be stored on separate disks). When more than
one disk is used, each of these disks is controlled by separate
commit cache processes, which are linked to each other in order to
enable and control (asynchronous) parallel read and write
operations.

The commit cache makes certain that the database file is

consistent, even if a power failure should occur during a write
operation to the disk.

However, when a power failure occurs, you will lose all committed
transactions currently held in the commit cache.

359
.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
you should not use advanced disk caches with delayed write back
(sometimes called lazy write). Using such cache systems may
cause your database file to be corrupted.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The figure below illustrates a database stored on three physical
disks. Each disk is controlled by its own commit cache process. All
processes are connected to enable parallel reading and writing.

DBMS

The commit cache Commit cache

enables
asynchronous Separate Separate Separate
parallel reading and Process Process Process
writing to the disks
in your system
Database

c: d: f:

360
 15.8 The Command Buffer

15.8 The Command Buffer

The command buffer is placed as a link between your application
and the DBMS in the C/SIDE system. It is a temporary storage
place that can hold requests (C/AL database commands) 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 LAN environments.

When an application performs a write transaction, some requests

such as inserting a record in a table (using record.INSERT()) need
not be sent to the DBMS at once, but can be stored in a command
buffer temporarily. In general, commands that do not have to
return a value for the execution of the C/AL code to continue do
not have to be sent immediately to the DBMS.

Notice that...
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 will be reduced (that is, the
load on the LAN will be reduced) as the time required to send one
DBMS request is comparable to the time used to send an entire
package.

The following illustrates an C/AL code sample where the command

buffer affects the number of network transfers.

WHILE Record.FIND('-') DO
Record.DELETE();

Two commands are executed for each record in the table, but each
record will only cause one request to be sent to the DBMS, as the
DELETE command will be stored in the command buffer until the
FIND command is executed.

361
.

Debugging The system automatically turns off the command buffer when you
activate the C/AL debugger. This can lead to some confusion if you
are not aware of this fact.

The statements below, supposed to be the complete contents of a

codeunit, will illustrate the difference between running code with
and without the debugger:

Customer."No." := '12';
Customer.DELETE();
First := 7;
Second := 0;
Ratio := First / Second;

Now, suppose that there is no Customer with No. 12. A run-time

error will occur whether the debugger is active or not–-but the
error that occurs will not be the same. There are two errors here:
since the Customer cannot be found, the DELETE will fail, and the
last statement is a division by zero.

When the debugger is inactive, the DELETE command will be

absorbed by the command buffer for later execution. Therefore, a
run-time error will occur when the last statement tries to divide by
zero.

When the debugger is active, the DELETE command will be

executed immediately, causing a run-time error when the
Customer record cannot be found.

362
Appendix F
Report Flow Charts

This appendix illustrates the flow of control for

reports in C/SIDE.
.

15.6 Report Flow charts

The following sections contain flow charts that show the flow of
control for reports in C/SIDE.

As indicated by the legend below, some processes in one flow

chart are ‘exploded’ in the following pages in order to show more
details.

Legend
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Entry point

Exit

Process

Process with subpages

BWT Begin Write Transaction

EWT End Write Transaction

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

364
 15.7 Report.Run

15.7 Report.Run

365
.

Report.Run

Call Init
Trigger

Set DataItem
TableViews

ReqForm.Run

Cancel

OK / Print / Preview

BWT

Set DataItem
ReqFilters

Call PreReport
Trigger

Clear DataItem
Filters

PageNo=1

DataItem.Run

Get Next DataItem OK

No more

Call PostReport
EWT
Trigger

366
 15.8 DataItem.Run

15.8 DataItem.Run

DataItem.Run

Clear DataItem

Property:
True Hold
PrintOnlyIfDetail

Set DataItem
TableView False

Body.Run

Set DataItem
ReqFilter

Transfer DataItem
Link DataItem.Run
Header.Run
No
Get next lower
OK
DataItem
TotalArray:
Append Group/ (OnlyFirst)
Grand totals
No more

TotalArray:
Update Group/
Call PreDataItem
Grand totals
Trigger OK GroupHeader.Run
NewPage

Property:
True
TotalArray: NewPagePerRecord
Clear Totals

False

GetRecord

Property:
Skip / Break True RollBack
PrintOnlyIfDetail

Skip
Break False

NextRec =
No more
NextRec = NULL GetNextRec(Curr
Rec)

CurrRec = OldRec

GroupFooter.Run

TotalArray:
SwapTotal
(GrandTotal)

Call PostDataItem
Trigger
Footer.Run

(OnlyLast)

367
.

15.9 Section.Run

Section.Run (Transport)

Get Next Section No More

OK

Call PreSection
Trigger

NewPage

Calculate Space
Not Enough
Need (Param:
Transport)

Enough

Call PostSection
Trigger

Print Section

368
 15.10 Header.Run

15.10 Header.Run

Header.Run (IncludeBack,UsePrintOnEveryPage,OnlyFirst)

Param: Not
True OldRec
OnlyFirst NULL

NULL
False

Hold

Back.Header.Run

Param:
True
IncludeBack
(IncludeBack)

False

Param:
Property:
UsePrintOnEvery True False
PrintOnEveryPage
Page

False
True

Section.Run

369
.

15.11 Footer.Run

Footer.Run (IncludeBack,UsePrintOnEveryPage,OnlyLast)

Param: Not
True NextRec
OnlyLast NULL

False
NULL

Param:
Property:
UsePrintOnEvery True
PrintPnEveryPage
Page

False
True

Property:
True Move to Bottom
PlaceInBottom

False

TotalArray:
SwapTotal
(GrandTotal)

False

Section.Run

TotalArray:
SwapTotal
(GrandTotal)

Param:
IncludeBack

True
False

Back.Footer.Run

(IncludeBack)

Param: Not
True NextRec
OnlyLast NULL

NULL

False
RollBack

370
 15.12 TransHeader.Run

15.12 TransHeader.Run

371
.

TransHeader.Run (IncludeBack)

Back.Trans
Header.Run
Param:
True
IncludeBack
(IncludeBack)
False

OldRec NULL

Not NULL

TotalArray:
SwapTotal
(LastGroup)

Section.Run

TotalArray:
SwapTotal
(LastGroup)

372
 15.13 TransFooter.Run

15.13 TransFooter.Run

TransFooter.Run (IncludeBack)

OldRec

Not NULL

TotalArray:
SwapTotal
(LastGroup)

Section.Run
NULL

TotalArray:
SwapTotal
(LastGroup)

Param:
False
IncludeBack

True

Back.Trans
Footer.Run

(IncludeBack)

373
.

15.14 GroupHeader.Run

374
 15.14 GroupHeader.Run

GroupHeader.Run

Get next
GroupTotalField No more
(forward in key)

OK

Check
Not
GroupTotalField
Changed
(OldRec-CurrRec)

Changed

Hold

NewPage

Property:
Not
OldRec NewPagePer True
NULL
Group

NULL False

TotalArray:
SwapTotal
(LastGroup)

Section.Run

TotalArray:
SwapTotal
(LastGroup)

375
.

15.15 GroupFooter.Run

GroupFooter.Run

Get next
No
GroupTotalField
more
(backward in key)

OK

Check
GroupTotalField Changed
(CurrRec-NextRec)

TotalArray:
Not
SwapTotal
Changed
(GroupTotal)

Section.Run

(Transport)

TotalArray:
SwapTotal
(GroupTotal)

TotalArray:
GroupChange

RollBack

376
 15.16 Body.Run

15.16 Body.Run

Body.Run

Section.Run

Property:
True
PrintOnlyIfDetail
(Transport)

False

Commit

377
.

15.17 NewPage

NewPage (Transport)

TransFooter.Run

Param:
True
Transport
(IncludeBack)

False

Footer.Run

(IncludeBack)
(UsePrintOnEvery
Page)

PageBreak

Increment PageNo

Header.Run

(IncludeBack)
(UsePrintPn
EveryPage)

TransHeader.Run

Param:
True
Transport
(IncludeBack)

False

378
 15.18 GetRecord

15.18 GetRecord

GetRecord

Yes

Break No OldRec = CurrRec

TotalArray:
ClearTotalVars

CurrRec =
No
GetNextRec
more
(CurrRec)
No
OK more

Auto Calculate
FlowFields

Skip = No
Break = No

Call
AfterGetRecord
Trigger

OK

379
.

380
Index

A statements 251
application Symbol Menu 243
application object 8 syntax errors 299
design 14 where to place 278
design (reference to books) 20 C/AL debugger 310
object 5 C/AL functions
the term 8 CALCFIELDS 288
array 257 CALCSUMS 289
ascending order 38 CONFIRM 295
DELETE 287
B DELETEALL 288
ERROR 295
binary (field data type) 28
FIELDERROR 289
BLOB 29
FIELDNAME 290
C/AL data type 256
FIND 283
field data type 29
GET 282
boolean
GETRANGEMAX 285
C/AL data type 253
GETRANGEMIN 285
displaying 130
INIT 291
field data type 28
INSERT 286
bound control 91, 122
LOCKTABLE 288
bound form 91
MESSAGE 294
breakpoint 311
MODIFY 286
bugs 298
MODIFYALL 287
NEXT 283
C
OPEN 294
C/AL
overview 282
bugs 298
SETCURRENTKEY 284
comments 275
SETFILTER 285
constants 258
SETRANGE 284
control language 268
STRMENU 295
data types 253
TESTFIELD 291
debugger 310
UPDATE 294
debugging 298
VALIDATE 291
defined 9, 250
cache 356
dialogs 292
commit cache 358
editor 7, 236
DBMS cache 356
essential functions 282
CalcFormula (property) 45
expressions 251
calculation formula 45
function calls 266
card form 93
Globals 241
creating 94
Locals 242
CASE 270
operator hierarchy 266
char (C/AL data type) 254
operators 264
check box to display booleans 130
program logic errors 307
code
repetitive statements 271
C/AL data type 255
reusing code 279
field data type 28
run-time errors 301

377
Index

codeunit image 113

accessing functions 246 in reports 167
compiling 244 indicator 136
creating 238 input 124
defined 236 label 113
limitations 246 menu button 114, 153
running 237 menu item 114
saving 244 moving 103
specifications 326 multiple selection 100
temporary tables 236 option button group 128
codeunit (C/AL data type) 256 option drop-down 127
Color tool 119 picture box 133, 135
column 24 properties of, in forms 121
commit properties of, in reports 187
in C 352 shape 113, 133, 134
in C/AL 352 sizing 104
commit cache 358 static 113
COMMIT() 353 subform 114
company 40 tab control 114, 137
Company system table 74 table box 114, 138
complex data types 256 text box 116, 117, 122, 126
compound statement 268 toolbox 115
concurrency 347 tools 119
conditional statements 269 ToolTip 124
consistency 347 types of 113
constant 258 unbound 91, 122
container control 90, 113 control types 113
frame 132
control D
adding 115 data 27
aligning 104 data container 114
bitmaps 135 data controls 113
bound 91, 122 data integrity 344, 350
branch 91 data item 167, 168
changing caption 121 data model 188, 197, 204
changing name 121 defined 10
check box 130 properties 186
Color tool 119 data model 15
command button 114, 131 data type
container 90, 113, 132 binary (field) 28
container control selection 102 BLOB (C/AL) 256
control branch selection 102 BLOB (field) 29
data 113 boolean (C/AL) 253
data types 113 boolean (field) 28
defined 10 char (C/AL) 254
display properties 122 code (C/AL) 255
displaying numbers 122 code (field) 28
Font tool 119 codeunit (C/AL) 256
formatting data 123 complex (C/AL) 256
frame 114, 132 controls and data types 113

378
Index

date (C/AL) 254 delayed write back 358

date (field) 28 descending order 38
decimal (C/AL) 254 descriptional data types 255
decimal (field) 28 Designer
descriptional (C/AL) 255 Dataport 7
dialog (C/AL) 256 Form 7
file (C/AL) 256 Object 6
form (C/AL) 256 Report 7
fundamental 253 Table 7
integer (C/AL) 253 dialog 292
integer (field) 28 C/AL data type 256
mixing 328 document 224
option (C/AL) 253 Documentation section 237
option (field) 28 drill-down 150
record (C/AL) 256 form 150
report (C/AL) 256 Drive virtual table 79
table fields 27
text (C/AL) 254 E
text (field) 28 editor
time (C/AL) 254 purpose 7
time (field) 28 using 236
data version Entity-Relationship (ER) model 15
defined 346 EXIT 274
historical 349 expression
storage of 348 basic elements of 258
database defined 251
defined 11 evaluation 252, 328
design 14
design (reference to books) 20 F
logical 11
field
physical 11
defined 9
the term 8
illustration 24
Database File virtual table 83
property 54
Database Key Groups system table 75
trigger 59
Dataport Designer 7
Field Menu
date
in reports 176
C/AL data type 254
file (C/AL data type) 256
field data type 28
File virtual table 78
Date virtual table 77
FlowField
DBL_BWT 353
calculation formula 45
DBL_EWT 353
defined 42
DBMS 344
table filter 48
cache 356
FlowFilter field 42
specifications 324
Font tool 119
deadlock detection 351
FOR TO/DOWNTO 271
debugger
form
breakpoint 311
bound 91
decimal
card form 93, 94
C/AL data type 254
closing 106
field data type 28
compiling 107

379
Index

creating 93, 94, 97, 98 groups 75

description 90 in ER model 17
design 90, 141, 142 list 30, 33, 36
drill-down 150 performance 34
Form Wizard 93 primary 30
lookup 147 property 56
main form 140 secondary 31
running 107, 152 SumIndexFields 340
saving 106
specifications 326 L
subform 140 lazy write 358
tabular form 93 Locals 242
test-compiling 107 locks 350
unbound 91 log file 346
form (C/AL data type) 256 logical database 11
form design lookup 144, 147
Color tool 119 form 147
Font tool 119 table relation 146
toolbox 115 looping (C/AL) 271
tools 119
Form Designer 7, 90 M
Form Wizard 93, 94
main form 140
creating a card form 94
design 141
creating a tabular form 97
Member Of system table 73
function
menu
accessing in codeunit 246
design 153, 154
C/AL 236
menu button 153
creating 240
menu item 153
fundamental data types 253
menu line 154
shortcut key 155
G Monitor virtual table 79
global variable 236
Globals 241 N
groups in reports 204
nonprinting report 228
Number 256
I
ID number 5 O
IDE 4
Object Designer 6
IF THEN ELSE 269
OnRun section 237
integer
operators
C/AL data type 253
arithmetic (type conversion) 332
field data type 28
hierarchy 266
Integer virtual table 78
logical (type conversion) 331
integrity 344
relational (type conversion) 330
using in C/AL 264
K option
key C/AL data type 253
defined 9 field data type 28
discussed 30 order

380
Index

ascending 38 documents 224

descending 38 execution 171
Field Menu 176
P flow chart 171
performance grouping 204
command buffer 360 nonprinting 228
commit cache 358 properties 167, 184
DBMS cache 356 property, description of 185
keys 34 report description 167
measuring 80 Report Designer 175
Permission system table 74 report triggers 212
physical database 11 request form 167
program logic errors 307 Request Options Form Designer 175, 177
finding 317 running 180
property saving 179
CalcFormula 45 section 167, 168, 192
control 91, 110, 121, 122, 123, 124 Section Designer 175
control, general properties 112 section properties 187
defined 9 section triggers 213
fields 54 specifications 326
form 91, 110 totaling 204
inheriting 110 totals 206
key 56 triggers 167, 212, 218
list of, in forms 111 virtual tables in reports 214
list of, in reports 167 report (C/AL data type) 256
Property Sheet 92 report description 167
report 184, 185 Report Designer 7, 175
table 52 request form 167
TableRelation 61 Request Options Form Designer 175, 177
Property Sheet 92 RequestForm 167
defined 10
R row 24
run-time errors 281, 301
read consistency 347
finding 315
record
C/AL data type 256
defined 24 S
relationship 61 section 167, 168
REPEAT UNTIL 273 defined 10
report designing 192, 199, 207
closing 179 properties 187
compiling 180 triggers 213
control 167 Section Designer 175
control properties 187 Session virtual table 81
controlling output 221 shortcut key 155
data item 167, 168, 188, 197, 204 specifications
data item properties 186 codeunit 326
data item triggers 212 DBMS 324
data model 188, 197, 204 forms 326
definition 166 reports 326
designing sections 192, 199, 207 tables 325

381
Index

statement field data type 28

compound 268 text box
conditional 269 adding 116, 117
defined 251 adding a label 122
String 256 calculation 126
subform 114, 140 multiple lines 126
design 142 time
SumIndexField C/AL data type 254
and FlowFields 42 field data type 28
defined 340 toolbox 115
Symbol Menu 243 ToolTip 124
syntax errors 299 totals
system table 71 and sections 206
Company 74 totals in reports 204
Database Key Groups 75 transaction 344
Member Of 73 trigger
Permission 74 control 92, 159
User 72 data item 212
User Group 73 defined 9
system-defined variable 280 field 59
form 92, 158
T overview of control triggers 159
tab control 114 overview of form triggers 158
table overview of report triggers 212
adding records 39 report 167, 212
defined 24 table 59
description 24 type conversion 328
modifying the design of 66
property 52 U
relationship 61 unbound control 91
saving 37 changing to bound 122
specifications 325 unbound form 91
system 71 User Group system table 73
temporary 68 user interface 4
trigger 59 User system table 72
validating relationship 147 user-defined variable 259
viewing data in 37
virtual 76 V
Table Designer 7, 26 variable
Table Information virtual table 84 arrays 257
table relation 146 assignment 262
and assist edit 64 creating 240
example 63 CurrForm 280
TableRelation property 61 CurrReport 280
tabular form 93 global 236
creating 97 initialization 262
template 10 naming conventions 260
temporary table 68 Rec 280
text system-defined 280
C/AL data type 254 user-defined 259

382
Index

xRec 280
virtual table 76
advanced 77
Database File 83
Date 77
Drive 79
File 78
Integer 78
Monitor 79
Session 81
simple 77
Table Information 84
virtual tables 214

W
WHILE DO 272
WITH 274
write locks 350
write transaction 344

383
Index

384