Gxap PDF

Designing Applications
MONTEVIDEO URUGUAY CHICAGO USA MEXICO CITY MEXICO SAO PAULO BRAZIL
Av. 18 de Julio 1645 P.4 - (5982) 402 2082 400 N. Michigan Ave. Suite 1600 - (312) 836 9152 Mariano Escobedo 353 A Of. 701 - (5255) 5255 4733 Rua Samuel Morse 120 Conj. 141 - (5511) 5502 6722
Desinging Applications in GeneXus Copyright ARTech Consultores S. R. L. 1988-2006. All rights reserved. This document cannot be reproduced by any means without the express consent of ARTech Consultores S.R.L. The information contained in this document is for the personal use of the reader. TRADEMARKS ARTech and GeneXus are registered trademarks of ARTech Consultores S.R.L. All the trademarks mentioned in this document are the property or their respective owners.
Page 2 of 111
Desinging Applications in GeneXus
Table of Contents
Introduction .................................................................................................................... 5 1. Developing an application .............................................................................................. 7
Defining the objective ............................................................................................................... 7 Defining the work team ............................................................................................................. 7 Obtaining a global idea .............................................................................................................. 8 Defining the scope of the application ........................................................................................... 8 Keeping design simple............................................................................................................... 8 Being Data Oriented.................................................................................................................. 8 GeneXus Methodology ............................................................................................................. 10 GeneXus Objects .................................................................................................................... 11 Elements ............................................................................................................................... 12 Structure............................................................................................................................... 14
Attributes ...............................................................................................................................................16 Domains .................................................................................................................................................18 Key Attributes .........................................................................................................................................18 Relationship between the structure and the data model ................................................................................19 Other simple transactions of our application ................................................................................................19 Defining the Orders transaction .................................................................................................................20 Transactions referential integrity ...............................................................................................................21 Transaction levels ....................................................................................................................................22 Types of relationships between the objects .................................................................................................26
2. Transaction object .......................................................................................................12
Forms ................................................................................................................................... 27
Field to field dialog...................................................................................................................................28 Full screen dialog.....................................................................................................................................28 Positioning Buttons ..................................................................................................................................28 Input and output attributes .......................................................................................................................28 Selection Prompt Feature..........................................................................................................................29 Controls .................................................................................................................................................30 Attribute/variable controls type .................................................................................................................31 Customizing the Orders form ..................................................................................................................32 Tools Palette ...........................................................................................................................................33 Control properties ....................................................................................................................................34 Properties, Methods and Events Editor........................................................................................................37
Form Editor ........................................................................................................................... 30
Formulas ............................................................................................................................... 37
Horizontal Formulas .................................................................................................................................38 Vertical Formulas.....................................................................................................................................39 Formulas and Redundancy ........................................................................................................................40 Formulas of Formulas...............................................................................................................................41
Rules .................................................................................................................................... 41
Default ...................................................................................................................................................41 Error ......................................................................................................................................................42 Assign ....................................................................................................................................................42 Add and Subtract.....................................................................................................................................43 Serial .....................................................................................................................................................43 Evaluation Order......................................................................................................................................44 Call ........................................................................................................................................................45 Rules triggering events and conditions .......................................................................................................45
3. Report object ..............................................................................................................47

Elements ............................................................................................................................... 47 Layout .................................................................................................................................. 47 Source .................................................................................................................................. 49
Properties.............................................................................................................................. 46
FOR EACH Command ...............................................................................................................................50 Reports with several FOR EACH commands .................................................................................................58 Other commands .....................................................................................................................................64
Conditions ............................................................................................................................. 68 Rules .................................................................................................................................... 69

Default ...................................................................................................................................................69 Parm ......................................................................................................................................................69
Report Wizard ........................................................................................................................ 70 Properties.............................................................................................................................. 74
Page 3 of 111
Desinging Applications in GeneXus 4. Dynamic Reports GeneXus Query ................................................................................75 5. Procedure object .........................................................................................................77
Deleting data ..........................................................................................................................................78 Adding data ............................................................................................................................................79
6. Work Panel object .......................................................................................................80

Elements ............................................................................................................................... 80 Example................................................................................................................................ 80 Form .................................................................................................................................... 83
Grid .......................................................................................................................................................83
Integrity and redundancy controls............................................................................................. 79
Events .................................................................................................................................. 85
Start Event .............................................................................................................................................86 Enter Event.............................................................................................................................................86 User-Defined Events ................................................................................................................................87 Refresh Event..........................................................................................................................................87 Loading data to the work panel .................................................................................................................88
Conditions ............................................................................................................................. 90 Data order in the grid.............................................................................................................. 91 Rules .................................................................................................................................... 91

Noaccept ................................................................................................................................................91 Search ...................................................................................................................................................92 Fixed Bitmaps .........................................................................................................................................93 Dynamic Bitmaps.....................................................................................................................................93
Bitmaps ................................................................................................................................ 93 Properties.............................................................................................................................. 95 Object-Action Dialogs .............................................................................................................. 96 GeneXus Browser .................................................................................................................. 97
7. Web object .................................................................................................................98 Appendix A. Relational Data Models ...................................................................................99

Transactions .......................................................................................................................... 98 Web Panels............................................................................................................................ 98
Primary Key and Candidate Keys ...............................................................................................................99 Referential Integrity ...............................................................................................................................100 Indexes ................................................................................................................................................ 101 Normalization........................................................................................................................................ 102 Extended table ...................................................................................................................................... 103
Appendix B. Functions, rules and commands ..................................................................... 105 Figures Index ............................................................................................................... 109 NOTES: ....................................................................................................................... 111
Page 4 of 111
Introduction
This document is an introduction to developing applications using GeneXus. It is aimed at IT professionals who are new to this tool. GeneXus is a tool for the development of applications on databases, which helps systems analysts implement top quality applications in the shortest possible time. In general, application development involves analysis, design, and implementation tasks. GeneXus approach to this objective consists in freeing users from automatable tasks such as implementation and allowing them to focus on more complex, non-automatable tasks (understanding the user problem.) From a theoretical point of view, GeneXus is a tool associated with an application development methodology which shares some points with more traditional methodologies, but provides quite different approaches to other issues. Like traditional methodologies, it continues to stress application analysis and design over implementation. GeneXus provides clear evidence of this approach in that its developers will spend most of their time on analysis tasks1, while GeneXus itself will be performing design and implementation tasks database normalization, database creation, program generation, and so on. On the other hand, some methodological approaches are quite different from the usual ones, such as starting the application analysis from the user interface, or the fact that there is almost no reference to the systems physical implementation. GeneXus methodology starts from describing the user visions to model the system. Based on this model, GeneXus automatically builds the IT support (database and programs). To introduce these new concepts and to avoid being too abstract, we have chosen an application that will be developed through the chapters of this book. The first chapter introduces the application and initial considerations for developing with GeneXus. The following chapters present some of the GeneXus objects for describing applications, which are used to develop the sample application. Thus, the second chapter is about the Transaction object, the third chapter deals with the Report object, the fifth chapter deals with the Procedure object, the sixth chapter is about Work Panels, and lastly we deal with the objects to work in Web environments. All these chapters require basic relational database skills, so we have included an appendix providing the necessary concepts on the subject to fully understand this document. We recommend reading the appendix before the second chapter of this manual. For didactical reasons, the following issues are not included in this document: Applications life cycle: Applications have a life cycle that starts when they are planned, and ends when they are launched. GeneXus accompanies this cycle. Use of GeneXus This book uses GeneXus version 8.0.
This is the reason why GeneXus users are usually called GeneXus analyst instead of GeneXus developers.
1
Page 5 of 111
Desinging Applications in GeneXus A Trial Version of GeneXus is available for download at: http://www.genexus.com/trialversion The GeneXus Developer Library (GXDL) centralizes all the technical information and has been created to provide developers with a unique source of information, strengthened with a search engineering that will enable them to access technical information on the different ARTech products swiftly and easily (release notes, manuals, tips, whitepapers, etc). You can query it online or use it locally, by means of a simple installation (http://www.gxtechnical.com/gxdl) If you have any suggestion or comment regarding this edition, please let us know about it at the following address: gxusatraining@genexus.com
Page 6 of 111
1. Developing an application
The application that we have chosen is a simplification of a real one: Purchasing system for a pharmacy chain. A pharmacy chain wants to implement a purchasing system that provides purchasing analysts with the most amount of information possible. The purchasing analysts responsibility is to decide which orders should be placed with suppliers to restock products. System operation The purchasing analyst should use a computer to create products orders to send to suppliers. Once the orders are made and approved, the system will issue the purchase orders. When creating an order, it is necessary to make several queries, such as how many products are left in stock, which was the last order price, and so on. The following sections describe the steps followed to develop this application.
Defining the objective

Computers are only tools, and systems users have specific goals or objectives in using them. They expect the applications to help them achieve these objectives faster and at a lower cost. Therefore, the analysis work should identify the users objectives as well as the activities they perform to achieve them. This objective should be expressed in a few words with it. Some of the possible objectives are: "The purchasing system should lessen the bureaucracy around order placement." "The purchasing system should enable non-trained users to place orders as if they were experts." "The purchasing system should allow for the reduction of stock in the stores." From all possible goals, one should be chosen as the main or priority objective. This is crucial for the future design of the application: just note how each objective leads to a different design. For this example, well choose the first objective because in the real situation the purchasing analyst didnt have all the necessary information. As a result, he had to read forms and manuals, and call the warehouse employees so that they performed a manual stock counting. We shouldnt confuse the application objective (WHAT) with its functionality (HOW the objective will be achieved). and all those involved should be familiar
Defining the work team

Next we should define the team that will be in charge of the system implementation. This team should have at least two members: The Systems Analyst A User
Page 7 of 111
Desinging Applications in GeneXus The Systems Analysts working on the application development should fulfill two conditions: Be trained on the use of GeneXus Be application-oriented We recommend that these analysts spend some time working with the users at the beginning of the project to get familiar with the concepts, vocabulary, existent problems, etc. Because an application is developed incrementally, user participation is CRUCIAL in all the development stages. Its advisable to have a principal user available for prototype testing, as well as keep in close communication with the other users. When working with GeneXus, team members will devote most of their time to design tasks, not to codification tasks. Therefore, the general criteria should be to work in small teams, for example, of no more than five persons.
Obtaining a global idea

We should have interviews with the highest possible management level in order to obtain information about the relative position and priority of the application within the organization.
Defining the scope of the application

After a primary study we should decide which will be the scope of the application in order to achieve the objective. For that purpose, it is advisable to follow the Essentiality Principle: Only whats necessary, but all thats necessary. Once that a purchase order is sent to a supplier, we should control how and when the products are actually delivered. However, we realize that this isnt necessary to achieve the applications objective, so it wont be included.
Keeping design simple

Planning should be based on an incremental design and development process, starting with small steps and frequently checking the models evolution with the users.
Being Data Oriented

Basically, an application is a group of steps to perform certain processes on certain data. Therefore, in the application analysis, you can give more importance to processes or to data. In traditional methodologies -as the Structural Analysis- the analysis is based on processes. Generally, this analysis is top-down: it begins with the most abstract definition of the system function, and then breaks it up in gradually simpler functions, until reaching a level abstract enough to implement them directly. This approach, however, has some problems: A systems functions tend to evolve with time. Therefore, a function-based design will be difficult to maintain.
Page 8 of 111
Desinging Applications in GeneXus The idea that an application may be defined by a unique function is very controversial regarding medium or big applications. The data structure analysis is frequently neglected. It doesnt facilitate the integration of applications.
If, on the other hand, the design is based on the data, we can obtain the following advantages: More stability. Data tends to be more stable than processes, and consequently, the application will be easier to maintain. Easy integration with other applications. An application rarely is completely independent from the other applications in an organization. The best way to integrate them is by taking into account the data that they share.
Thus, a data oriented approach seems to be more beneficial. The obvious question is then: how should we analyze data? The GeneXus answer is to directly analyze the data that the user knows, no matter how it will be implemented in the system. The design process begins -as youll see with more detail in the following chapter- by studying which are the objects that the user manipulates. For each one of these objects, first we define its data structure, and then we define its behavior. In this way we achieve two important objectives: the analysis is focused on facts, and it can be directly evaluated by the users through the GeneXus prototyping capabilities.
Page 9 of 111
GeneXus Methodology
To start developing an application with GeneXus, the first step consists in creating a new project or knowledge base. The following step is describing the users visions, from which GeneXus captures and systematizes the knowledge. For this, objects from the real world must be identified and defined through GeneXus objects. With the definition of these objects, GeneXus can withdraw the knowledge and automatically design the database and the application programs.
If an object from the real world changes or new or different characteristics of this object are identified or an object that has not been modeled yet is found, GeneXus analyst must reflect these changes in the corresponding GeneXus objects and the tool will automatically make the required modifications in the database and in the associated programs. GeneXus methodology is an incremental methodology, since it is based on the premise that a system is built through successive approximations. GeneXus analyst defines the current knowledge, and then, when this knowledge increases or changes- GeneXus will automatically perform all required customizations in the database and the programs. If GeneXus was not capable of making these modifications automatically, as changes requiring them occur, incremental development would be unfeasible. GeneXus can generate applications in different platforms. E.g.: the application can be implemented for a DBMS such as Sql Server, Oracle, Informix, etc., in a language such as .NET, C/SQL, Visual Basic, Visual FoxPro, etc. Tables, indexes and programs will be generated by GeneXus in the selected platform, and the analyst will not need to have a deep knowledge of the language or the DBMS. Conclusion: although GeneXus increases applications development productivity significantly as regards traditional methodologies, the strongest point is the notorious reduction of maintenance costs.
Page 10 of 111
GeneXus Objects
Following you will find a description of the most important GeneXus objects (which are not the only ones): Transactions2 They allow defining objects from the real world (real or imaginary) that the user handles (e.g.: purchase analyst, items, suppliers, orders, etc.). They are the first objects to be defined, since GeneXus infers the database design through the transactions. Each transaction has an associated screen for windows environment and another one for web environment. They enable the user to add, delete and modify database elements interactively. GeneXus analyst will decide if he will work in window environment, in web environment or in both of them. Reports They allow retrieving information from the database and displaying it, on the screen, in a file or printed on paper. These are the typical lists or reports. They do not allow updating the database information. Procedures They share the report characteristics but, unlike them, they also allow updating the database information. Work Panels They enable the user to interactively make queries to the database through a screen, in windows environments. E.g.: a work panel allows the user entering a characters range and then shows all the customers whose names are within this range. They are very flexible objects that can be used in multiple ways. They do not allow updating the database, they only allow querying it. Web Panels They are similar to work panels, but they are used through browsers in Internet/Intranet/Extranet environments.
Do not confuse with database transaction that applies to the group of operations to be executed on the database, which must be executed either all of them or none of them. In GeneXus, this concept is known as Logical Transactional Unit (LTU).
Page 11 of 111
2. Transaction object
Every GeneXus application analysis starts with the transactions design. The transactions allow defining objects from the real world. To identify the transactions that must be created, we recommend paying attention to the names mentioned by the user when describing the real world. In addition to the definition of the real world and the resulting creation of the normalized database3, each transaction involves the generation of programs for windows environment and web environments to allow for the interactive addition, deletion and modification of database elements. GeneXus analyst will decide if he will generate programs to work in windows environment or in web environment or in both of them. Therefore, besides determining the structure of a table -like the rest of the GeneXus objects that we will analyze later- transactions cause the generation of programs. You should bear in mind that the entire development process is incremental and therefore there is no need to define every transaction in detail in this stage. What matters is identifying the most important ones and then identifying and defining the structure of each of them. In order to identify the most relevant transactions, it is advisable to study the objects, either real or imaginary, that the user manipulates. Most transactions can be found in:
Description of the system. When users describe a system, many transactions may be determined by paying attention to the words they use. For example: Purchasing Analysts Orders Suppliers Items Purchase Orders
Existing Forms. For every form used in the system, most likely there will be a transaction to enter it.
Elements
For every transaction you may define the following elements, among other: Structure It allows defining the attributes (fields) that make up the transaction and the relations between them. Based on the transaction structure, GeneXus will infer the database design: tables, keys, indexes, etc. GUI-Windows Form Each transaction has a GUI-Windows form (Graphical User Interface Windows) (screen), through which additions, deletions and modifications will be performed in Windows environments. Web Form Each transaction has a Web form (screen), through which additions, deletions and modifications will be performed in Web environments.
3
GeneXus designs the database in third normal form.
Page 12 of 111
Desinging Applications in GeneXus Rules Rules allow defining transactions specific behavior. E.g.: they allow defining attributes default values, data verifications, etc. Events Transactions support an event-oriented programming. This type of programming allows defining idle code, which is activated in response to specific actions caused by the user or the system. Subroutines They allow defining routines that are local to the transaction and are executed when called from the transaction itself. Properties They are characteristics to be set up to define specific details as regards the transaction general behavior. Associated Style Styles are GeneXus objects used to define standards. We will not deal with them in this document. Help It allows including tooltips to be queried by the users in the transaction runtime. Documentation It allows including technical text to be used as system documentation. On defining/editing a GeneXus object (either a transaction or any other one), you can access the different elements making it up using the tabs appearing at the bottom of the object editing window. In a transaction, these tabs are the following:
Fig. 1: Tabs at the bottom of the transaction editing window
The Web Form tab is available in case you want to generate the transaction for Web applications, so that it can run on a Browser. Basically, this tab is for modifying the Web form that has been created. We will study this point in the chapter dealing with Web Objects.
Page 13 of 111
Structure
The structure defines which attributes (fields) integrate the transaction and how they are related.
Fig. 2: Suppliers transaction structure
In the example, the Suppliers transaction has the following attributes, which make up the desired information on a supplier. SupCod SupNam SupAdd SupOrdTot Supplier Supplier Supplier Supplier Code Name Address Order Total
Based on this structure, GeneXus will build a table: SUPPLIERS

SupCod SupNam PrvDir PrvTotPed
And it will create a default GUI form for the transaction:
Fig. 3: GUI Form of the Suppliers transaction
As well as a Web form:
Page 14 of 111
Fig. 4: Web Form of the Suppliers transaction
The analysts will be able to modify these forms later. Through this form (either the GUI or the Web one, which will depend on the environment for which the application is generated), the user will be able to enter new suppliers that will be added as new records in the associated table. He will also be able to modify the data of a given supplier. For this, the Suppliers transaction has an encapsulated logic that enables it to access the associated table, retrieve the requested record and show its data in the form so that the user can visualize them and modify them. Once the data appearing in the form has been modified (e.g.: the supplier name has been changed), the transaction will make this change in the corresponding physical record, when suitable. A similar process occurs regarding records deletion. GeneXus analyst does not need to program any of these actions, since they are implicit in the transaction logic. GeneXus performs the coding, which is absolutely transparent for the analyst, who must only take care of the high level aspects concerning the object. As we will see later, when we represent transactions in GeneXus we are: Explicitly: defining the user interface in data presentation and capture. Implicitly: defining the relation between data (tables, indexes, etc.)
Page 15 of 111
Attributes
Each application attribute has associated properties that can be edited to be modified. E.g.: the following screen corresponds to the properties of the SupCod attribute defined:
Fig. 5: Define Attribute Dialog
As we can see, the screen has four tabs: General It allows setting up the general attribute characteristics, such as: Name: The attribute name. It is used to identify it. Description: The attribute long name or detailed description. It must identify the attribute well, regardless of the context, and it must be understandable by the end user. It must be an attribute global identifier; that is to say, the same description must not be assigned to two attributes of the same application, since -as we will see in the chapter dealing with Dynamic Reports- based on this description and using the GeneXus Query tool, the end user will select attributes to define his own queries to the database. The Title and Column properties are related to the Description. They appear underneath, on the properties edition screen. By default, they take the same value specified in Description, which can be modified later by the analyst. These properties are described below: Title: By default, the description entered here will be placed next to the attribute, each time the attribute is used in flat outputs. In figures 3 and 4 corresponding to the Win and Web forms of the Suppliers transaction (flat forms), the Supplier Code appears on the left of the SupCod attribute, which is the Page 16 of 111
Desinging Applications in GeneXus value appearing in the attribute Title property, as we can see in figure 5. Column Title: By default, the description entered here will be placed as attribute title each time it is included as grid column. In figure 5, in the Column Title property of the SupCod attribute, we modify the default value, shortening the description. Thus, when this attribute is included as grid column, instead of appearing with the Supplier Code description it will appear simply with Code (please refer to figures 9 and 64 to see two examples of the above). These two titles allow defining the descriptions that we want to display together with the attributes each time they are included on the default screens of the GeneXus objects. Domain: It allows associating a domain to the attribute. On assigning a domain to an attribute, certain attributes properties will be disabled (such as Data Type and Length) and will take the domain values. If the attribute does not belong to a domain, this property will keep the value (none); therefore, the properties corresponding to the attribute data type will appear enabled so that the analyst can specify their values. Data Type: It allows indicating the attribute data type. It will allow the user to select one of the data types supported by GeneXus. Some of them are: Numeric, Character, VarChar, Long VarChar, Date, DateTime and Blob. The properties available to be set up by the user will depend on the data type selected. Length: It allows indicating the attribute length. If in the Data Type property the attribute is defined as numeric type, the user must bear in mind that the length must include the decimal positions, the decimal point and the sign. This property will be disabled when the selected data type does not require establishing the length (e.g.: Date data type). Decimals: If the attribute is defined as numeric in the Data Type property, this property will be offered to specify the decimals amount. In this field, value 0 will define an integer number. Signed: if the attribute is defined as numeric in the Data Type property, this property will be offered to indicate whether a sign will be managed or not. The default value is False, which indicates that negative values will not be represented. Value Range: it allows indicating a range of valid values for the attribute. E.g.: 1:20 30: - means that the valid values are those between 1 and 20; and 30 or higher. 1 2 3 4 means that the valid values are 1, 2, 3 and 4. 'S' 'N' means that valid values are 'S' and 'N'. Autonumber: It allows indicating that the attribute must be automatically numbered by the system. It only applies if the attribute is numeric type and primary key of the table. If the attribute is not primary key, the autonumbering may be solved through the Serial rule -that we will see later- or by procedure. Initial Value: When an attribute is being added to an existing table that has records already loaded, this property allows specifying the initial value to be given to this attribute for the pre-existing records. Picture: It allows indicating the edit format for the attribute input and output. The properties appearing under this category depend on the attribute data type. E.g.: in case of numeric data type, the user can specify whether he will use thousands delimiter or Page 17 of 111
Desinging Applications in GeneXus not; in case of character data type, he will be able to specify if he wants all characters to be accepted and automatically displayed in capital letters, etc. Control Info It allows indicating the control type to be associated to the attribute. This information is used by GeneXus when it creates the default forms. The type of related information to be requested depends on the control type selected. We will see this point later, when dealing with the transaction forms. Help Every attribute can be assigned a long description to help the end user in runtime. If the end user requests help pressing F1 on the attribute, this description will be displayed. Documentation It allows defining attribute technical documentation, which is useful for developers.
Domains
When creating the database, its common to find attributes that share similar definitions but cannot be directly related, such as names, which are usually saved as character type with a length of 25. Domains address these situations by allowing the use of generic attribute definitions. For example, the Suppliers transaction name is SupNam, and later on an analysts name will also be defined. In this case, it is possible to create a Names domain of character type with a length of 25, and associate it to these attributes. Thus, if the domain definition changes at any time, all the attributes that belong to it will be automatically updated. Domains are not attribute-exclusive elements. You can also define a variable as belonging to a specific domain and the same considerations mentioned above will be valid in this case. In figure 2, corresponding to the structure of the Suppliers transaction, you can see that the SupNam attribute belongs to the Names domain (to which we will assign the Character (25)) data type. And the SupOrdTot attribute belongs to the Amounts domain (to which we will assign the Numeric(9,2) data type, where 2 correspond to the decimal position).
Key Attributes
You should always define the attribute, or group of attributes, that identify the transaction with unique values. If in the real world that we are modeling, a supplier is identified by his code, the SupCod attribute will the identifier of the Suppliers transaction. In GeneXus, this is indicated through the key on the left of the attribute in the transaction structure, as clearly shown in figure 2. Frequently, attribute lists are used as notation to represent a transaction structure on paper (either in books, GeneXus manuals, help, etc.). Those attributes acting as identifiers appear followed by an asterisk. E.g.: the Suppliers transaction structure would be represented as follows: SupCod* SupNam SupAdd SupOrdTot Here, we are representing that the identifier of the Suppliers transaction is the SupCod attribute; that is to say, there cannot be two suppliers with the same code. This uniqueness will be automatically verified in runtime.
Page 18 of 111
Desinging Applications in GeneXus Information about identifiers: Every transaction should have an identifier. Identifiers have a value from the beginning. For example, when creating a new supplier you should already know its SupCod. Identifier values dont change. For example, the supplier coded 123 cant be changed for it to have code 234. If you cant determine an identifier based on the attributes that represent relevant information of the object from the real world. You should create an artificial attribute that doesnt exist in the real world and whose value is automatically assigned by the system.
Relationship between the structure and the data model

GeneXus captures the required knowledge from the transactions structure to define the corresponding data model. From the structure of the previous example, GeneXus infers that: There arent two suppliers with the same SupCod. For each SupCod there is only one value of SupNam, SupAdd and SupOrdTot. It uses this information to build the data model. In this case, GeneXus determines that it must create a table that will have the same name as the transaction by default. This table will be made up by the four previous attributes, and SupCod will be the table primary key: SUPPLIERS
SupCod SupNam SupAdd SupOrdTot
In this book we will be analyzing this notation for the tables where the attributes acting as primary keys appear underlined. We say that the SUPPLIERS table is associated to the Suppliers transaction meaning that, when data is entered, modified or deleted through this transaction, it must be also physically entered, modified or deleted in the associated table. Likewise, GeneXus will automatically create an index by primary key, which will be called ISUPPLIERS. It will be used to perform and efficient uniqueness control of the primary key as well as referential integrity controls, as we will see later on. The table and index names are automatically assigned by GeneXus, using the transaction name, but the analyst will be able to modify them, if desired.
Other simple transactions of our application

In addition to the Suppliers transaction, we have transactions to represent and manage important information on purchase analysts, items and orders. The structures of the fist two ones will be as follows: Analysts: AnlNum* AnlNam Analyst number Analyst name
Page 19 of 111
Desinging Applications in GeneXus Items: ItemCod* ItemDsc ItemQty ItemLstPurDat ItemLstPurPrc ItemUn ItemSiz ItemAva Item code Item description Quantity in stock Last purchase date Last purchase price Item unit Item size Item availability
The ANALYSTS and ITEMS tables will be associated to them, respectively. ANALYSTS
AnlNum AnlNam
ITEMS
ItemCod ItemLstPurPrc
ItemDsc ItemUn
ItemQty ItemSiz
ItemLstPurDat ItemAvai
As we can see in these transactions, all the structure attributes are present in the associated table. Nevertheless, this is not the most frequent situation, as we will see later on, when defining the orders transaction. Based on the transactions structure, GeneXus creates a GUI-Windows form and a Web form by default for each transaction; both forms will establish their user interface in Windows and Web environments, respectively.
Defining the Orders transaction

Consider the transaction to manage the information related to the orders: The existing orders form is the following: Order : Analyst : Supplier : Code 321 567 1456 21 John Smith 125 ABC Inc. Description Aspirins Flogene Quantity 100 120 Date : 02/01/02
Price 30 50 Total
Subtotal 3000 6000 9000
Without considering the orders items, the header transaction attributes are: OrdNum* Order number OrdDat Order date AnlNum AnlNam SupCod SupNam OrdTot Order total Where OrdNum is an order identifier. There are some interesting points to note about this transaction: the attributes AnlNum and Page 20 of 111
Desinging Applications in GeneXus AnlNam as well as SupCod and SupNam are also included in other transactions. This is to indicate that there is a relationship between Analysts and Orders, and also between Suppliers and Orders. Above all, it indicates that every order has ONE analyst and ONE supplier. Thus, attribute names are the way to let GeneXus know the relationships between the transactions.
Rules for attribute names

The same attribute should have the same name in all the transactions where it appears4. Therefore, the supplier name is SupNam in the suppliers transaction as well as the orders transaction. Conceptually different attributes should be named differently, even if they are in the same domain. For example, the supplier name and the analyst name are in the same domain (Character type with a length of 25), but they refer to different data, so they should be called differently: SupNam and AnlNam.
Transactions referential integrity

When you define a transactions structure, you ARE NOT describing exactly the tables structure, but the data required for the screen (form), in the transaction rules or events. For example, although AnlNam appears in the Orders transaction structure, this attribute will not belong to the table corresponding to the transaction. It was included so that it appears in the Orders screen (form). The table associated to the Order header will be: ORDERS
OrdNum OrdDat AnlNum SupCod OrdTot
This table will be automatically created by GeneXus, together with the following indexes: IORDERS (OrdNum) Index by Primary Key IORDERS1 (AnlNum) Index by Foreign Key IORDERS2 (SupCod) Index by Foreign Key Note that neither SupNam nor AnlNam are included in the ORDERS table because GeneXus normalized and there is a relationship between the SUPPLIERS table -where SupCod is primary key- and the ORDERS table -where it appears as foreign key. This relationship, called referential integrity, ensures that: In order to insert or update a record in the ORDERS table, the corresponding SupCod should exist in the SUPPLIERS table. In order to delete a record from the SUPPLIERS table, there shouldnt be any records in the ORDERS table with the SupCod value to be deleted. These integrity constraints are automatically generated by GeneXus in the transactions.
4 In the GeneXus course we deal with cases where this is not possible, and then we introduce the subtype concept that allows us naming the attribute differently, but specifying that it belongs to the same concept. We will not study this topic in this book.
Page 21 of 111
Desinging Applications in GeneXus Thus, when you assign a value -in runtime- to the SupCod attribute in the Orders transaction, GeneXus checks that it exists in the SUPPLIER table. Besides, to help the user so that he does not need to remember GeneXus valid values by hard, it generates a selection screen called Prompt or Selection list, to view all the existing suppliers and to select one of them to be associated with the order, as we will see further on in this document (fig.9)
Transaction levels
Going back to the example, in order to complete the design of the Orders transaction you should enter the information about the orders Items (the lines) in the structure. If you define the structure as follows: OrdNum* OrdDat SupCod SupNam AnlNum AnlNam ItemCod ItemDsc OrdQty OrdPri OrdAmo OrdTot
Ordered quantity Price ordered Order Line Amount
you will not be modeling the real world correctly, since what you are representing here is that for each order there is only ONE item. Nevertheless, if we observe the pre-existing form, we clearly see that an order is made up by several items. Therefore, the correct structure is: OrdNum* OrdDat AnlNum AnlNam SupCod SupNam ( ItemCod* ItemDsc OrdQty OrdPri OrdAmo ) OrdTot
Header Level Lines Level
Where the identifier is OrdNum, and for each order number there is only one date, one analyst number and name, one supplier code and name and only one total, but there are many Items with their description, quantities ordered, prices and total amounts. In this notation, the brackets indicate that for each order there are many items. Every group of attributes between brackets belongs to a transaction LEVEL. Its important to point out that the first level is implicit and doesnt have to be between brackets. Thus, the Orders transaction has two levels: Page 22 of 111
Desinging Applications in GeneXus OrdNum, OrdDat, AnlNum, AnlNam, SupCod, SupNam, , and OrdTot, belonging to the first level, and ItemCod, ItemDsc, OrdQty, OrdPri and OrdAmo, belonging to the second level.
In GeneXus, the second level is represented as shown in the following figure:
Fig. 6: Orders transaction structure in GeneXus
Transactions can have many levels, and these levels may be nested or parallel. For example, if the order has many delivery dates you can define: OrdNum* OrdDat AnlNum AnlNam SupCod SupNam (ItemCod* ItemDsc OrdQty OrdPri OrdAmo) (OrdDelDat* OrdAmoPay ) OrdTot
Delivery date Amount to pay
This structure indicates that an order has many items and delivery dates, but that there is no direct relationship between them, except for the fact that they belong to the same order. If, on the other hand, Delivery Dates are established on a per-item basis (each item has its own delivery date), the correct structure is:
Page 23 of 111
Desinging Applications in GeneXus OrdNum* OrdDat AnlNum AnlNam SupCod SupNam (ItemCod* ItemDsc OrdQty OrdPri OrdAmo ( OrdDatDel* OrdAmoPay )) OrdTot Each transaction level has an identifier; that is to say, a group of attributes that determine the uniqueness of the attributes of the level. For example, the order transaction has ItemCod as second level identifier, which means that orders cant have two lines with the same ItemCod value Therefore, it wouldnt be possible to enter the following order: Order : Analyst : Supplier : Code 321 321 1 21 John Smith 125 ABC Inc. Description Aspirins Aspirins Quantity 100 120 Date : 02/02/01
Price 30 50 Total
Subtotal 3000 6000 9000
because there are two Order lines with the same ItemCod. If you want to represent orders like the previous one, where you can enter several lines belonging to the same item, the ItemCod attribute can no longer be the identifier of the second level. You must define another identifier. For this, you add an artificial attribute, OrdNum, in the second level. It will contain the line number. OrdNum* OrdDat AnlNum AnlNam SupCod SupNam ( OrdNum* ItemCod ItemDsc OrdQty OrdPri OrdAmo ) OrdTot
Page 24 of 111
Desinging Applications in GeneXus Where the OrdNum value may be entered by the user or a rule may be included in the transaction for it to be automatically assigned by the program;the "Serial" rule, which will be seen later in this book5. Thus, ItemCod is no longer identifier and it will be possible to repeat it for two different lines in the same order. Each transaction level has an associated table. For the Orders transaction with the structure that we have seen, GeneXus will create 2 tables: ORDERS ORDERS1
OrdNum OrdNum OrdDat AnlNum SupCod OrdTot OrdQty OrdPri OrdAmo
last
OrdNum
ItemCod
The primary key of the tables associated to the subordinated levels is the concatenation of the superior levels identifiers (OrdNum) plus the level identifiers (OrdNum). In the case of the first level, there is no higher level, therefore, the primary key corresponds to the level identifier. Just by defining the transactions structures, as we have done, GeneXus determines the tables to be created, the primary keys (based on the identifiers) and the foreign keys (based on the attributes names) of these tables and then, for each one of them, it defines and creates indexes by these keys found, to perform referential integrity controls more efficiently. Resides, GeneXus provides the possibility of defining candidate keys, that is to ay, groups of attributes of a table whose values must be unique. Every primary key is, specifically, a candidate key. Candidate keys are defined creating a user index for this group of attributes and defining it as unique (instead of duplicate). With this definition, GeneXus performs the uniqueness control for primary key in the transactions (as well as the referential integrity controls) and it also verifies the uniqueness of any candidate key defined through these indexes. Choosing the identifiers is an important task that may either simplify or complicate a system implementation. For example, suppose that the order doesnt allow the existence of more than one line with the same ItemCod. The most obvious way of implementing this is by defining ItemCod as the second level identifier. Now, if for any reason OrdNum was defined as the identifier, you will lose that automatic control, and you will have to resource to one of the following two solutions: Writing a procedure to perform it, or Creating a user index made up by the OrdNum and ItemCod attributes, in this order, and defining it as unique.
The creation of any index has costs related to the performance and the maintenance, since it must be kept updated. The more rules of the real world you reflect on the structure, the less processes you will have to implement, gaining simplicity and flexibility. From now on, we will keep just the first structure that we have seen for the Orders transaction, where the item code could not be repeated (i.e.: the second level identifier is ItemCod)
5 Here, it is not valid to set up the Autonumber property of the OrdNum attribute in True so that it is automatically numbered by the ssystem, since this attribute is not a primary key by itself.
Page 25 of 111
Types of relationships between the objects

When users are describing the application, we usually ask them about the relationships that exist between the different objects. For example, what is the relationship between the orders and the suppliers: One supplier has several orders One order has only one supplier.
Relations that match the previous requirements are called N-1 (which is read: ORDERS and SUPPLIERS have an N to 1 relation). The first requirement could be represented as follows: SupCod* SupNam .... (OrdNum* .... ) And the second one with the two following transactions: OrdNum* .... SupCod SupNam .... .... SupCod* SupNam SupAdd SupOrdTot
Note that the first design represents the first requirement but not the second one, since it allows the same order number to be associated to different supplier codes. With this design we are representing an N-M relation, which does not reflect the real world of the application of the example. The second design, instead, represents both requirements and thus, it is the and it is therefore the one that we have presented in the previous exposition.

suitable one
An order has many items. An item may be in many orders.
In this case we say that the relation between ORDERS and Items is N-M. The two possible structures modeling this relation are the following:
Page 26 of 111
Desinging Applications in GeneXus OrdNum* OrdDat SupCod SupNam AnlNum AnlNam ( ItemCod* ItemDsc OrdQty OrdPri OrdAmo ) OrdTot ItemCod* ItemDsc (OrdNum* OrdDat SupCod SupNam AnlNum AnlNam OrdTot OrdQty OrdPri OrdAmo )
Or
You should choose only one structure. In this case, the correct structure is the first one because users will enter the orders together with their items, and not the orders they have for each Item.
Forms
For each transaction, GeneXus creates a GUI-Windows form and a Web form, which will be the user interface in windows and web environments respectively. GeneXus creates both forms by default, the moment the transaction structure is saved. Both forms have all the attributes included in the transaction structure with their respective descriptions, in addition to some buttons. Although they are created by default, they can be modified to make them more colorful. E.g.: by changing edit type controls by other control types, by adding and/or deleting buttons, etc. The Suppliers transaction default GUI Windows Form is the following:
Attributes to be accepted or displayed
Fig. 7: GUI Form - SUPPLIERS transaction
Using this dialog box, end users can enter, modify and delete suppliers. To this end, it has a mode to indicate which operation is being performed (Insert, Update, Delete and/or Display) and users can switch modes without leaving the screen. GeneXus generates several types of dialogs for transactions, such as: field to field dialog and full screen dialog. The type of dialog to be used will depend on the environment (Windows or Web) and on the implementation platform that has been chosen.
Page 27 of 111
Field to field dialog

In this dialog, every time you type a value on a field, its validity is immediately controlled. E.g.: once the user enters a value in a Date type attribute and exits the field, the value corresponding to a valid date will be immediately controlled
Full screen dialog

In this full screen dialog, all the screen fields are accepted first and then all the validations are made. In Web environment, there is no other option but working in this way, since as data travels from the browser to a Web server and vice versa, working with the field to field dialog is not possible on account of time and traffic factors.
Positioning Buttons
Both GUI-Win and Web forms are initialized by default with positioning buttons. If we observe the GUI form of the SUPPLIERS transaction (fig.7), at the left of the top border we can see buttons enabling to select the first supplier: one shown on the screen: , a specific supplier: , the supplier following the , etc.
Besides, in the Web form shown on figure 4, we see these controls with a different look.
Input and output attributes

Consider the Orders transaction . The default GUI form is:
Fig. 8: Default GUI Form of the ORDERS transaction.
We can see a grid corresponding to the data of the second level, since for each order you must be able to enter several lines. Some of these attributes such as OrdNum and SupCod should be typed, Page 28 of 111 ( they are input
Desinging Applications in GeneXus attributes). Other attributes such as SupNam dont have to be typed because they are output attributes (their value is not shown.) GeneXus automatically determines which attributes can be typed in, and which ones are displayed, following the rules: Only those attributes that are physically in the table associated to each level can be accepted. In this case they are the ORDERS table attributes: OrdNum, OrdDat, SupCod, AnlNum and OrdTot and those of the ORDERS1 table: ItemCod, OrdQuty, OrdPric and OrdAmo) Attributes defined as formulas arent accepted (we will study formula attributes further on in this chapter). In Update mode the identifiers arent accepted. Attributes with Noaccept rules arent accepted. (we will study this and other rules further on in this chapter)-
Selection Prompt Feature

The Prompt feature is generated for the attributes involved in the referential integrity of the associated table (attributes that are foreign key). This feature allows visualizing the set of valid values for these attributesin order to be able to select one without having to remember it by hard. E.g.: in the ORDERS transaction generated in Win environment, by pressing a special key (by default F4) on the SupCod attribute, the following screen is displayed. It allows visualizing all the SUPPLIERS, to select one of them:
Fig. 9: SUPPLIERS Selection List
The fields appearing on the top of the screen correspond to variables that allow positioning on the grid over the first supplier with some of the values entered by the user in these variables and select it. This selection list is a work-panel-type object automatically created by GeneXus, since we assume that we are working in a Win environment. If we were working in a Web environment, GeneXus would create a similar object, although specific for this environment: a web panel. Once created, this object can be modified by the analyst as he would do with any work panel Page 29 of 111
Desinging Applications in GeneXus (web panel) created by him. In every transaction where a SupCod attribute is foreign key, the user will be able to access this screen to select a valid value. This screen is also displayed when a user presses the Select button in the SUPPLIERS transaction (see figures 3 and 4).
Form Editor
GeneXus objects that implement an interaction with the user, both to login and to display data, do this through a screen. Transactions and work panels in Win environment and transactions and web panels in Web environments are objects of this type, therefore they have associated forms. To design these forms, there is an editor for Win environments and another for Web environment that allow inserting and modifying the different controls that make up these screens.
Controls
A form is made up by controls. We can define a control as an area of the user interface that has a specific format and a behavior. There are different controls. We will mention some of them: Form: A form can be considered as a control in itself. Text: It allows placing fixed text (such as attribute descriptions: Supplier Name, Item Code or any other text). Attribute/Variable: It allows placing attributes or variables. Line: This control allows drawing horizontal and vertical lines. Box: It allows defining boxes of different sizes and formats. Grid: It allows defining data grids. Button: It allows including buttons in the forms. Bitmap: It allows defining static bitmaps.
The previous controls are available to be used in GUI-Windows or Web interface. The tab control is only available to be used in GUI-Windows interface, while the other controls can only be used in Web (text blocks, tables, grids freestyle, etc.). The edition of the GUI-Windows form is performed by selecting the object Form tab. In the following figure we show the GUI-Windows form of the Items transaction that we have customized, by changing the control type of some attribute controls:
Page 30 of 111

Button Controls
Text
Attribute Controls
Fig. 10:
Items transaction form
Attributes ItemUn, ItemSiz and ItemAvai do not appear in the form as conventional attributes (edit type). . ItemUn is defined as Combo Box, ItemSiz as Radio Button and ItemAvai as Check Box.
Attribute/variable controls type
Edit
Usually, attributes have a quite large value range; e.g.: a name, a price, etc. In these cases, the user is enabled to enter the attribute value and the system takes care of validating it. These types of controls are called Edit Box, or just Edit. In the previous figure, ItemCod, ItemDsc, etc. are examples of these Edit controls. Nevertheless, there are attributes with a smaller value range, which can be displayed beforehand so the user can select one of them. Thus, we can control that only valid values are entered. These types of controls are the ones that we will be seeing next.
Check Box
It is used for those attributes that have only two possible values. In our example, the attribute will take the values Y or N to indicate if an item is available. There is only one description (Available) and, in case this field is selected, the value will be specified by the analyst (in our example, Y). Otherwise, the other value will be specified (in the example N).
Radio Button
On the other hand, the Radio Button type of control may have more than two values. All the values are displayed on the form (in fact, their descriptions are displayed, the stored value is internally managed) and only one of them can be selected. In the example, the item size, ItemSz is defined as Radio Button.
Page 31 of 111
Combo Box
It is normally used for those attributes that have a large value range, for which using a Radio Button is not practical. An Edit type field is displayed and by pressing a button located on the right of the field, a list with all the valid values is displayed. We do not recommend using this type of control as selection list for attributes that can be read on a table. In these cases, we use Dynamic Combos.
Dynamic Combobox
A Dynamic Combobox is a type of control similar to the Combo Box. Their operation is similar, except that the values displayed are not static (entered by the analyst as fixed values). They are descriptions read from a specific database table.
List Box
This type of control has an associated items collection. Each item has an associated <value, description> pair. The control gives the possibility of selecting only one item at a time. The attribute or variable takes the value the moment the item is selected. The selection is made by clicking on an item or with the keyboard arrows. The List Box control can be considered as an open Combo Box; that is to say, the values (items) are shown displayed on a list, and the List Box definition and functionality is completely similar to the ones of the Combo Box.
Dynamic List Box

This type of control has an associated items collection. Each item has an associated <value, description> pair. The items collection is loaded from a database table in runtime. In design time, two attributes are associated to the Dynamic List Box; one of them is associated to the value that the item will have and the other one to the description that it will take. Both attributes must belong to the same table. In specification time, we determine the table from which the values and descriptions will be brought.
Customizing the Orders form

In fig.8 we have seen the form that GeneXus creates by default for the Orders transaction. In this form we can see that, a control text and a control attribute are inserted for each attribute of the structure first level. The control text corresponds to what has been set up for the attribute in the Title property, as we mentioned when we studied the attributes. For the attributes of the second level, there is a grid designed with a column for each attribute of this second level. The column title is the value of the Column title property of the corresponding attribute. Working with the forms editor we can customize the previous screen so that is remains as follows:
Page 32 of 111
Fig. 11: Customized form of the ORDERS transaction
The form is delimited by a frame whose title is the transaction description. It can be visualized like the control form. The different control types of the form edition that we have just mentioned will appear within it. Each control has a series of properties (line width, color, backcolor, font, etc), that depend on the control type and whose values can be fixed independently. Further on we will study the properties of some of the mentioned controls.
Tools Palette
When editing a form, several Tools Palettes are available as We have a tools palette that allows inserting controls: additional windows.
Fig. 12: Controls Tools Palette
And another one that allows aligning them, copy the size of one of them to another, etc.
Fig. 13: Form Editor Tools Palette
Page 33 of 111
Using the Tools

It is possible to perform several operations on the objects selected with the pointer: Change the size and shape of a control. Edit properties. Move Forward, Move Back, Move to Front and Move to Back. These operations allow you to change the layer in which a control is located. Each control is on a different form layer, so some of them are "above" others. When two objects overlap, the one on top will be displayed and the one below it will be only partially visible that is, those parts that arent covered. Move, Copy and Delete.
Control properties
These are the main properties of some controls that may be inserted in a form.
Attribute/ Variable
General Tab Attribute/Variable: It allows indicating the attribute or variable associated to the control. Name: This option is used to assign a name to the control that is being edited. This name will be used later to associate properties, events or methods to the control. In case of an attribute or a scale variable, it appears disabled, since the name of the attribute or variable is associated to the control. This property is enabled in case of a non-scale variable (i.e.: a vector or matrix). In the latter case, you must use a control for each atomic element of the non-scale variable. That is to say, if we have a variable called &numbers, which is a numeric type vector, with 3 Page 34 of 111
Fig. 14: Control attribute/variable Properties
Desinging Applications in GeneXus elements, we must insert 3 controls to show each of them in the form. In the Attribute/Variable, property of the 3 controls, the same (&numbers) variable will be selected, but the Name property of each control will be given a different name (such as one, two and three). Besides, in each control we must indicate what vector element it is. This is done in the Row and Column properties of the Array Indexes group. Here, we indicate expressions for the row and the column, so that the element is determined. Frame: Used to enclose an attribute or variable in a frame. Its possible to indicate its type: None, Single or 3D; the line(s) width, if it has Fill color, and if the size and shape are based on the attribute (Auto Resize). Array Indexes: In case of using non-scale variables, these properties are enabled to indicate the row and column of the non-scale variable that determine the element whose content is to be shown. Control Info Tab Used to select the control type; depending on the type it asks you to select other characteristics, including the control's Fore Color and Back Color. Control Type: In the generated Forms an attribute can be associated to different types of controls. You can select one of the following: Combo Box, Dynamic Combo Box, Radio Button, Edit, List Box, Dynamic List Box and Check Box. The Setup button that appears once the control type has been selected allows you to define specific features for the type of control selected. Fore Color: This button is for selecting the color with which the attribute value and the frame line(s) will be displayed. Back Color: With this button you can select a color to paint the attributes area on the screen. It only works if the Fill property is present. Font Tab It allows selecting the font to be used for the attribute or variable on the screen.
Page 35 of 111
Text
Fig. 15: Control Text Properties
Text. Used to insert texts to the screen; these texts can be of one or more lines. Wrap: It indicates if we want to adjust the text to the control size so that, when reaching the right top, what follows will be moved to the next line. Alignment: The text may be justified, left-aligned, right-aligned, or centered. Rest of the properties: They are analog to the Attribute/Variable control.
Rectangle
Fig. 16: Rectangle control properties
It is possible to select a border type for the Combo Box rectangle. The available options are: single, none (without border) or 3D.
Line
Uses the same properties edit dialog, but the Fill option is disabled.
Page 36 of 111
Properties, Methods and Events Editor

From all controls used in the forms, those that have associated names can receive associated properties, methods or events dynamically, by programming within the object. It is possible, for instances, to change a text font, show or hide a text, disable a button, and so on. The type of properties/events/methods that may be associated to a control depends on the type of control. The dialog box to associate properties to the controls is accessed through the Insert/Property option (Insert/Event and Insert/Methods for the events and methods, respectively) when editing the transaction events, rules or subroutines. The dialog box displayed is the following:
Fig. 17: Control Properties Selection Dialog
E.g.: if in the Orders transaction we want the line amount to appear in bold in case it is more than $1000, we can write the following transaction rules: OrdAmo.FontBold = 1 if OrdAmo > 1000; OrdAmo.FontBold = 0 if OrdAmo <= 1000;
Formulas
An attribute is a formula when its value may be calculated in terms of other attribute values. In the following example the OrdAmo attribute of the Orders transaction may be calculated from the order quantity OrdQty and the order price OrdPri: OrdAmo = OrdQty * OrdPri In each transaction you can indicate which attributes are formulas. This definition is global, which means that a formula is calculated each time that the attribute is needed in transactions and other GeneXus objects (Reports, Work Panels, etc). There are different types of formulas: Horizontal Vertical Aggregate/Select
Page 37 of 111
Horizontal Formulas
A horizontal formula is defined as one or more conditional arithmetic expressions. For example: if we add an attribute in the first ORDERS transaction level OrdDsc, which represents the discount applied on the order total, and we know that this discount is worked out as follows: If the order total is less than 100 the discount is not applied If the order total is within the range 100-1000, a 10% discount is applied If the order total is higher than 1000, a 20% discount is applied
The OrdDsc attribute will be defined as horizontal formula: OrdDsc = OrdTot * 0.10 OrdTot * 0.20 0 if OrdTot >= 100 and OrdTot <= 1000; if OrdTot > 1000; OTHERWISE;
In the expressions we can use arithmetic operands (+, -, *, /, ^), system functions (such as today(), which returns the current date), attributes, variables and constants, In case the calculation is very complex, we can call a routine to perform it. E.g.: OrdDsc = udp( 'OrdDisc', OrdTot )
Where 'udp' is a function that implements communication between GeneXus objects; 'OrdDsc' is the name of the called procedure; OrdTot is the parameter that is sent; OrdDisc is the attribute receiving the result of the procedure. The order amount is also a horizontal formula. OrdAmo = OrdQty * OrdPri As you can see, its calculation involves two attributes: OrdQty and OrdPri, but it doesnt specify in which tables they are stored. GeneXus finds a way to relate OrdQty and OrdPri in order to calculate the formula; in this case its very easy because OrdQty and OrdPri are in the same table. When it is impossible to relate the attributes, GeneXus gives the No Triggered Actions' message in the navigation list. We will refer to this message further on in this document. So, which attributes can be used? All the attributes a horizontal formula depends on should be in the same extended table as the attribute that is being defined as formula (see the concept of extended table in the Appendix about relational data models). Like with any other attribute, when we define one of the attributes of the transaction structure as formula, following the normalization criteria, GeneXus may directly determine the table that this attribute will be associated to. Based on this, it finds its extended table and if all the attributes used in the formula definition are in this extended table, the formula will be correctly defined and will be a horizontal type formula.
Page 38 of 111
Vertical Formulas
Now consider the Order Total (OrdTot): it should be calculated by adding the Amounts (OrdAmo) of each Order line. This formula is expressed as: OrdTot = SUM( OrdAmo ) This is a vertical formula. In this case the involved attributes arent in the formula extended table. In the example of OrdTot, if you look at the data model using the GeneXus table diagram, known as Bachman diagram, you will see that:
Table: ORDERS OrdNum* OrdDat AnlNum SupCod OrdTot 1 N Table: ORDERS1 OrdNum* ItemCod* OrdQty OrdPri OrdAmo
Fig. 18: Bachman Chart: ORDERS and ORDERS1 tables
OrdTot is associated to the ORDERS table and OrdAmo toORDERS1, which is a table directly subordinated to the ORDERS table. browser to determine which tables are subordinated and You can also use the GeneXus superordinated to ORDERS (by choosing the Subordinated Tables or Superordinated Tables option of the browser dialog box, respectively):
Page 39 of 111
Tables superordinated to Orders
Fig. 19: Browser: Purchase System
Apart from viewing the subordinated and superordinated tables, you can query the tables structure, which indexes it has (indexes composition), formulas, etc. There are two vertical formula operators: SUM, which adds all the data and COUNT, which counts the existing data.
Formulas and Redundancy

According to the normalization criteria, and given that formulas can always be calculated, it isnt necessary to store them because its enough to recalculate them each time they are needed. However, the fact that a formula isnt stored can cause performance problems due to the time it takes to recalculate it. To avoid this inconvenience you can define the formula as redundant. In this case, the formula is stored in the database and it isnt necessary to recalculate it each time that it is used. Once the formula is defined as redundant, GeneXus adds all the redundancy maintenance subroutines to all the transactions that use that formula to keep the database updated. Thus, the definition of redundant formulas implies a balance of performance on one hand, and storage and complexity of the generated programs on the other; the analyst should decide which option to choose. In theory this may seem a rather difficult decision, however, in practice we see that almost all redundant formulas are vertical, and a few times they are horizontal. The reason for this is that the calculation of vertical formulas may imply an unspecified number of readings. For example, to calculate the OrdTot it is necessary to read all the order lines, which can be quite many.
Page 40 of 111
Formulas of Formulas
A formula is calculated from the other attribute values, which can be stored or can be other formulas. For example, if the following is defined for the Suppliers transaction: SupOrdTot = SUM( OrdTot ) To calculate it you need: OrdTot = SUM( OrdAmo ) This also needs: OrdAmo = OrdQty * OrdPri For formulas of formulas, GeneXus determines the corresponding evaluation order: OrdAmo OrdTot SupOrdTot = OrdQnt * OrdPri = SUM( OrdAmo ) = SUM( OrdTot ) Total supplier order
Formulas are displayed in the transaction structure, as shown in the following figure:
Horizontal Formula Vertical Formula
Fig. 20: Formulas in the ORDERS transaction structure
Rules
Rules are used to define the behavior of transactions, including default values, constraints, and so on. These are some rules:
Default
It is used to define the default values of some attributes, for example: Default ( OrdDat, today() ); The default rule works differently depending on the type of dialog (full screen or field to field). In a full screen dialog the default value is assigned if the user doesnt enter anything in the field; in a field to field dialog the default value is assigned first and it may be modified later. Page 41 of 111
Error
It is the rule to specify the constraints that should be satisfied by the data. For example, to avoid that an item with zero quantity remains in an order, we write the following rule: error the order quantity must be higher than 0')) if OrdPri <= 0 ; When the condition is matched ( OrdQty <= 0 ) the following message is displayed on screen: '' The order quantity must be higher than 0', and users arent allowed to continue until they enter a correct value or quit the transaction. The error rule is commonly used to forbid the use of some transaction modes. E.g.: error( 'It is not allowed to delete Orders' ) if delete; This rule prevents users from entering the delete mode, and as a result, it is not possible to delete an Order.
Assign
The transaction rules allow making assignments to attributes and variables. The attribute assignments imply an update to the level base table, or to some tables of the level extended table. For example, consider the Items transaction: Items: ItemCod* ItemDsc ItemQty ItemLstPurDat ItemLstPurPrc ItemUn ItemSiz ItemAvai
Suppose you want to use the ItemLstPurPrc attribute to store the last order price of an item, and the ItemLstPurDat attribute to store the date on which this order was made. To achieve this, you have to define the following rules in the Orders transaction: ItemLstPurPrc = OrdPri if insert; ItemLstPurDat = OrdDat if insert; Thus, each time that you enter an order line the Items table is updated with the corresponding date and price. There are similarities between formulas and assignments, and even their definition syntax is similar. On the other hand, while formulas are GLOBAL (they are valid for all the GeneXus objects that use it), assignments are LOCAL, meaning that they are only valid for the transaction in which they were defined. When an attribute is a Formula, it is not stored (unless it has been defined as a redundant formula), but when its value is assigned by means of the assignment rule it is stored because it is local.
Page 42 of 111
Add and Subtract

The assignments you saw in the previous section were relatively easy, but there are more sophisticated cases. For example, in the same Items transaction there is an ItemQty attribute used to track the quantity in stock for each Item. Obviously, the Orders transactions must modify that value because every new order increases the stock level. Also, there will be another transaction (e.g.: Invoicing) to reduce the stock level, each time an item is sold.This transaction is beyond the scope of the project, so this book only covers the stock updating related to the Orders transaction. The ItemQty attribute should be updated in this transaction. This can be achieved with an Assignment: ItemQty = ItemQty + OrdQty; Remember that you can create, modify or delete an order in the same transaction. Therefore, the previous assignment is only valid when you are creating a new one; in case you are deleting it, the correct assignment would be: ItemQty = ItemQty - OrdQty; So, to correctly update ItemQty you would also have to consider the cases in which records are updated or deleted. In order to avoid all this, GeneXus provides the add rule to perform it automatically: add(OrdQty, ItemQty); With this rule, when an order line is inserted, OrdQty is added to ItemQty; if it is deleted, it is subtracted, and if it is modified, the previous value of OrdQty (defined as old(OrdQty)) is subtracted and the new value is added. There is a duality between the SUM vertical formula and the add rule or, more precisely, a redundant SUM is equivalent to the add rule. For example, the OrdTot may be defined as: OrdTot = SUM( OrdAmo ) and redundant or add( OrdAmo, OrdTot ); Vertical formulas usually have to be redundant for performance reasons, therefore, its advisable to use the ADD rule instead of the SUM formula. The subtract rule is equivalent but it does the opposite operations: In insert mode it performs a subtraction, whereas in delete mode it performs an addition.
Serial
This rule is useful to automatically assign values to a certain transaction attribute. For example, consider the second option for the Orders transaction, in which an item can appear more than once in the same order: OrdNum is the second level identifier, and if you want this number to be automatically assigned by the system, you may use this rule: serial(OrdNum, OrdLstLin, 1); where first parameter defines which attribute is being numbered, the second one indicates which attribute has the last assigned value (the last line number assigned), and the third Page 43 of 111
Desinging Applications in GeneXus parameter is the increase rate, which in this case is one by one. The OrdLstLin (Last line assigned) attribute should be included in the transaction structure at OrdNum level, because an order only has ONE last line assigned: OrdNum* .... OrdLstLin ( OrdLinNum* .... ) OrdTot In this way, the program automatically assigns a number to each new order line. In a field to field dialog, in which the mode is automatically inferred, a nonexistent value should be entered in OrdLinNum (usually 0) and the program assigns the corresponding value. In a full screen dialog the value is assigned when the user presses Enter in Insert mode.
Evaluation Order
The definition of rules is a DECLARATIVE way of defining the transaction behavior. The order in which they are defined doesnt necessarily coincide with the order in which they are found in the generated program; i.e.: the order in which they are executed. GeneXus determines the correct order according to existing dependencies among attributes. For example: Suppose that a new attribute has been defined in the Items transaction: ItemMaxQty, of the same type of ItemQty. This attribute will indicate the maximum stock quantity set for an item. When entering an order, a message should be given if the items maximum stock quantity is exceeded. To that end, the following rules have been defined in the Orders transaction: msg( 'Maximum stock quantity has been exceeded' ) if ItemQty > ItemMaxQty; add(OrdQty, ItemQty); The evaluation order will be: add(OrdQty, ItemQty); msg( 'Maximum stock quantity has been exceeded' ) if ItemQty > ItemMaxQty; The add rule modifies ItemQty and the msg rule displays that attribute. This implies that the msg rule should ask for ItemQty ItemMaxQty, and not for ItemQty + OrdQty greater than ItemMaxQty. greater than
Every time you create a new transaction, you can use the Detailed Navigation option that lists which is the rules evaluation order. This list indicates the generation order (usually called trigger order) not only of the rules, but also the formulas and table readings.
Page 44 of 111
Call
Call is a rule and a command used to call another program that may be any other GeneXus object. For example, from a transaction you may call a report or another transaction, or even an external program. When adding a call rule its necessary to define the moment in which the call should be triggered. For example, to call a report that prints the order that has just been entered in the Orders transaction, you should use this rule: call(RImpRec, OrdNum) On AfterComplete ; where 'RPrnOrd' is the called program and OrdNum is the passed parameter. The AfterComplete enter event means that the call will be made after the Order is completed. The use of the AfterComplete event is not exclusive to the call rule, and may be used in other rules.
Rules triggering events and conditions

In the transaction, there are system events that are related to the different moments taking place while entering data. E.g.: there is an event that occurs immediately after having inserted the record corresponding to the header in the associated table. There is another event that occurs immediately before this. Another event occurs immediately after having inserted all the records (header and lines), etc. These events are known as triggering events, since they are used to condition the moment a rule is executed (triggered). Likewise, most rules allow specifying a triggering condition, which is a Boolean condition that may involve attributes, variables and functions and that may be made up using the logical operands: or, and not. Summing up: a rule triggering may be conditioned by specifying a Boolean condition and/or one or several triggering events. Besides, a rule may be conditioned for it to be triggered only in some transaction levels. The level is specified naming one or several attributes of the corresponding level through the level clause. If this clause is not mentioned, the first level is assumed. According to what we have seen, the rules syntax remains as follows: rule[if <cond>] [On <event>] [level <att>]; Triggering events are related to the moments when the database records are physically saved/updated/deleted. Following you will find a description of the different events that may occur.
AfterValidate
It occurs after data of the transaction level we are currently working with is confirmed, but before executing the corresponding physical update. Sometimes it is used for automatic numbering in cases where it is not possible to use the serial rule to avoid concurrency control problems.
Page 45 of 111
AfterInsert | AfterUpdate | AfterDelete

A rule conditioned to some of these events will be triggered immediately after inserting, updating or deleting the record of the level base table. It is mainly used to call procedures that perform updates.
AfterLevel
Triggered after entering all the level data. Mostly used for controlling totals; for example, if you add a total (which may be called OrdTotEnt) when entering the Order header, to check if it matches the calculated total we will write the rule: error( 'Entered total doesnt match the calculated one' ) if OrdTotEnt <> OrdTot On AfterLevel Level ItemCod; where control will be performed just after you finish entering all the order lines.
AfterComplete
Triggered after entering all the transaction data. It is mainly used to call other transactions or programs that print the data. In environments that have transactional integrity this event occurs after performing the transaction commit.
Properties
In the Transaction Properties editor you can choose specific settings to define its general behavior. This is the dialog box to modify them:
Fig. 21: Transaction Properties Dialog
For example, it is possible to set properties related to both the transactional integrity and the interface. You can indicate if you want the transaction to make a commit at the end, or if you want confirmations to be asked every time that you update a level, and so on.
Page 46 of 111
3. Report object
With reports you define non-interactive processes for data retrieval. Reports are listings whose output can be printed, displayed on screen, or sent to a file. It is a non-interactive process because the data is first retrieved and then displayed, without any interaction with the user during the retrieval process; it is retrieval-only because this data cant be updated.
Elements
For each Report, you have to define the following elements, among other: Layout Reports have an output layout the same way as transactions have a screen (form). In this session we define the report presentation: data to be listed and output format. Source Here, we write the code corresponding to the report logic. It may also be defined at the end of the subroutines code that can be called from the code itself through the suitable command. Rules - Properties They define report general aspects such as name, description and output type (printer, file or screen), parameters received by the object, etc. Conditions Conditions to be matched by data to be retrieved (filters). Help Text to help users get questions answered about the Report. Documentation Technical text for use in the system documentation. Tabs to access elements Like in every GeneXus object, you can access several elements that make up the object using tabs appearing at the bottom of the object editing window:
Fig. 22: Tabs appearing at the bottom of the report editing window
Layout
In this session we define the data to be listed and the output format. The Layout is a sequence of blocks known as print blocks. These blocks are areas that will be displayed on the resulting list and that will contain the controls that will indicate what we want to print, providing a format to the output. E.g.: lets say that we want to implement a report to print the code, name and address of all our suppliers, and we want the list to look as follows:
Page 47 of 111
Fig. 23: Suppliers list in runtime
To implement this list, we create a report object and define all the required print blocks in its layout session. In this example, we could divide the output in two areas: one of them with fixed data and the other with variable data. Each area would be implemented with a print block. The corresponding layout is shown below:
Fig. 24: Layout of the Suppliers list
The print blocks order within the layout is not important: in this section they are simply declared. The order in which they will be displayed in the output is determined in the Source session, the one that contains the report logic. From there, they will be called to be printed, through a specific command (the print command). For this reason, each print block must have a name, so that it will be later referred to from the Source. This name is the one appearing on the left of each print block, in the Layout of figure 24. The print block is a new control type, and is only valid in reports and procedures. It indicates that the information specified within it must be shown in the output. This information is represented by other already studied controls (attributes, texts, boxes, lines, etc.). To list the code, name and address of all the SUPPLIERS, the print block called Supplier will have to be called within a repetitive structure in the Source, so that all the SUPPLIERS are scanned and the data of the supplier where the mouse is currently positioned will be printed each time. This repetitive structure is the for each command that we will introduce later. Like any other control, the print block has specific associated properties that may be set up from a dialog that is opened by double clicking on the control. Some of these properties are the paper type, the font type, etc. The dialog is the following:
Page 48 of 111
Fig. 25:
Print Block Control Properties
To design print blocks we have the same Controls tools palette as for transactions. The options enabled are the ones applying to this object type:
Print block
Fig. 26: Controls Tools Palette in Reports
This palette allows inserting attributes, texts, lines, boxes, bitmaps and new print blocks. Within the report, controls are inserted and set up like in the transactions form editor.
Source
The report logic is programmed in this session. The language used is very simple and has some commands. The programming style is procedural (imperative); therefore, the Source will be a sequence of commands for which the order is important, since it will be the execution order. Like in any other imperative language, there are control commands for conditional execution (if, do case), repetitive execution (do while, for), for calling another object (call), for stopping interactions within a loop (exit) or for exiting the program (return). This language also has specific commands to print a Layout print block (print), to access the database (for each),to call a subroutine (do), etc. At the end of the source, you can define subroutines (through the sub command), which will be local to the object. You will be able to call them further up, within the same source, in the execution code, through the do command, The following is the Source that implements the logic of the report of the example:
Page 49 of 111
Fig. 27: Source of the SUPPLIERS list
Where we have the Header, Print and For each commands. Obviously, with the print command we send the print block to be printed in the output. All the print blocks sent to be printed between the Header and end commands are lines printed on the page header. There is also the Footer command that allows printing a page footer on each page.
The For each command indicates that each one of the records of a specific table will be queried, showing the information indicated in the print block(s) that is(are) sent to be printed within the command. In this case, GeneXus infers that it must browse the SUPPLIERS table showing the code, name and address of each supplier.
FOR EACH Command

This command is of fundamental importance since it is the only command that allows retrieving information from the database. The information to be read is defined using the for each. This is achieved by naming the attributes to be used and NEVER specifying the tables from which they will be obtained or the indexes to be used. With this command we define WHAT attributes we need and in which ORDER we want to retrieve them and GeneXus will take care of finding out HOW to do this. Obviously, this is not always possible, and in these cases GeneXus gives a series of error messages indicating the reason why the involved attributes cannot be mutually related. The reason why there is no reference to the physical data model is because in this way the report specification of the highest possible level so that, when there are changes in the database structure, the report specification will be kept valid most of the time. The database access is specified by the attributes used in a FOR EACH ENDFOR group, and GeneXus will search the extended table containing that set of attributes. At this point, the concept of extended table is very important, so we suggest that you revise its definition in the Appendix about Relational Data Models. For example, in the previous Report the attributes SupCod, SupNam and SupAdd are used inside the FOR EACH ENDFOR. GeneXus "knows" that those attributes are in the SUPPLIERS table:
Page 50 of 111
Desinging Applications in GeneXus For each print Suppliers endFor is interpreted by GeneXus as: For each record in table SUPPLIERS Print SupCod, SupNam y SuppAdd endFor For clarification purposes, a report involving data from many tables is included below. This is a listing of all the orders headers:
Fig. 28: ORDERS list in runtime
The Layout for this list is:
Fig. 29: ORDERS list Layout
The Bachman diagram of the model tables is the following:
Page 51 of 111
Fig. 30: Model Bachman Diagram
In the previous list, the required data is in these tables: SUPPLIERS (SupNam), ANALYSTS (AnlNam) and ORDERS (OrdNum and OrdDat). The extended table of ORDERS contains all those attributes, therefore, the FOR EACH command will be interpreted as: For each record in the ORDERS table Find the corresponding SupNam in SUPPLIERS table Find the corresponding AnlNam in ANALYSTS table Print OrdNum, OrdDat, SupNam y AnlNam endfor When a report is specified, GeneXus provides a list ,called Navigation list, indicating which are the tables being accessed:
Sequentially scanned table
Accessed tables
Fig. 31: Navigation list of the ORDERS list report
The first table represented here indicates which is the for each base table; the indented tables below that one are the tables that must be accessed from each base table record where the cursor is positioned each time. . A practical interpretation of this diagram: many records are read for the table of the first indentation level, and for each table of the following Page 52 of 111
Desinging Applications in GeneXus level only one record is read: the one associated to the previous level. In this small tables diagram appearing in the list, the relation between the tables of an indentation level with any other nested table is N-1.
Order
The order in which the data would be listed was not taken into account in previous Reports. When this order is not indicated, GeneXus uses the order of the primary key of the For Each base table (there are some exceptions to this rule). This navigation list indicates the base table of each for each and, immediately, the order selected to retrieve the information. As shown in figure 31, GeneXus indicates that it will sort by OrdNum; that is to say, by the attribute that is primary key of the for each base table. To explicitly define the display order of the data, the ORDER clause is used in the for each command. For example, to list the orders sorted by Supplier Code, SupCod: For each ORDER SupCod print Orders endfor In this case the index will be the one called IORDERS (SupCod) of the ORDERS table, which was automatically defined by GeneXus since SupCod is a foreign key. The navigation for this report is as follows:
Fig. 32: Fragment of the navigation list of the ORDERS list report
If we want the ORDERS list output sorted by date, we do the following: For each ORDER OrdDat print Orders endfor In this case, there is no index defined in ORDERS to match the order, since OrdDat is not a key in any place. Since there is no defined index, GeneXus will indicate in the navigation list, by means of a warning, that there is no index matching the order. This may cause performance problems, depending on the implementation platform, the quantity of table records to be read, etc. In some platforms, such as VFP or iSeries (AS/400), if there is no index to match the specified order a temporary one is created each time the report is executed, and it is deleted when the execution is completed. This type of index is called temporary index. In other platforms such as VB with Access or in client/server environments, if there is no index to match the order, the For Each is translated into a sql query (select), which is solved by the platform DBMS engine. Page 53 of 111
Desinging Applications in GeneXus In this case, the navigation list will show the following:
Fig. 33: Navigation list of the ORDERS list report sorted by date
Obviously, this process is slower when compared to the previous list, which had a defined index. In this case you have to choose one of the available options: Create a User-Defined Index. In this case, the report will be much more efficient, but there is one more index to maintain, meaning that the transactions will have to store more data and run more processes to keep this index up to date. Do not create the user indexes and allow the navigation to be solved by the dbms or through the creation of a temporary index.
At this stage it is not possible to decide which is the best solution, so each particular case must be analyzed, considering how frequently the Report will be executed. However, if the index is not defined at the beginning and you want to define it later, you only have to regenerate the report (without modifying anything) and the Report will start using the index. The following is the ordering criteria used by GeneXus: Every FOR EACH group can be sorted by ANY set of attributes belonging to the base table of the group, but it cannot be sorted by attributes that are NOT in the table. For example, the previous list cannot be sorted by SupNam because the base table of the group is ORDERS, and the SupNam attribute is not stored in this table. Nevertheless, if the implementation platform is client/server, the criteria is wider and it will be also possible to sort by extended table attributes (in this case, it will be possible to sort it by SupNam).
Page 54 of 111
Conditions in the FOR EACH

The WHERE clause is used to restrict the listed data. For example, to list only todays orders: For each WHERE OrdDat = Today() print Orders endfor Several WHERE clauses can be defined inside the FOR EACH: For each WHERE OrdDat = Today() WHERE OrdNum > 100 print Orders endfor This means that BOTH conditions must be matched, that is to say, both clauses are assumed to be related by AND. If you want to use OR (when only one of the two conditions has to be matched), you should use only one WHERE: For each WHERE OrdDat = Today() OR OrdNum > 100 print Orders endfor GeneXus has the ability to optimize the report in terms of the FOR EACH order and conditions. When the condition has been optimized, it appears in the Navigation List as Navigation Filter, and when it hasnt, it appears as Constraint. For example, the part of the Navigation List corresponding to the following for each of a report: For each order OrdDat WHERE OrdDat = &today print Orders endfor Where &today is a system variable containing today's date:
Fig. 34: Fragment of navigation list of optimized for each
Page 55 of 111
Desinging Applications in GeneXus Note that the Navigation filters specify the range of the table to be scanned for the later selection of the filters appearing as Constraints. On the previous list there is no Constraint, which means that every record of the specified range will be printed. In this case, the range to be scanned is not the entire table. Since we are sorting by OrdDat and filtering by OrdDat, there is no need to scan the entire table. Since we have chosen an order compatible with the filters, GeneXus can optimize the access to the tables. Below appears the same report, but this time without specifying the ORDER clause in the For Each: For each WHERE OrdDat = &today print Orders endfor In the Navigation List, it shows the following:
Fig. 35: Fragment of navigation list of non-optimized for each
Here, we did not specify an order; therefore, GeneXus selected the base table primary key. This list shows us that it will be necessary to scan the entire ORDERS table, and print each record that matches the Constraints. This report does not optimize the access to the tables, since we did not sort in an order compatible with the filters.
WHEN NONE clause of a For Each

In several cases there is no need to execute a specific code when we do not find any record in a For each. For this, we use the WHEN NONE clause. Example: For each where OrdDat = Today() print Orders WHEN NONE Msg(No order was made in the current day ) endfor It is to be pointed out that, if we include For Eachs in a When None clause, we cannot infer Joins or filters of any kind regarding the For Each containing the When None.
Page 56 of 111
Determining the extended table of the FOR EACH group

Its very important to know how GeneXus determines the extended table that must be used. The basic rationale is this: Given the set of attributes inside a FOR EACH ENDFOR group, GeneXus determines the MINIMUM extended table that contains them. Lets say that we want to list the name of the analyst and the supplier of each order. For this, we will write the following in the Source: For each print NameSupplierAnalyst endfor where NameSupplierAnalyst will be the name of the Layout print block that will contain the SupNam and AnlNam attributes. Note that the only difference with the ORDERS list that we made before is that here we are not interested in listing the order number or the date; we are only interested in listing the analyst and the supplier. Now, the attributes participating in the determination of the For Each base table are SupNam and AnlNam. The minimum extended table that contains the For Each attributes is still ORDERS. Nevertheless, it may happen that there is more than one minimum extended table that contains the attributes of the FOR EACH ENDFOR group. In these ambiguous cases, GeneXus chooses the FIRST extended table that matches the conditions stated before. Example: Lets say that we add a Contacts transaction to our application to represent the contacts made by the analyst with a supplier to request quotations. We are interested in keeping a history of these contacts. For this, we define the following structure: AccNum* SupCod SupNam AnlCod AnlNam AccDat Contact Number
Contact Date
If we draw a Bachman diagram representing the following tables: ORDERS, ANALYSTS, SUPPLIERS and CONTACTS, we will have the following:
Page 57 of 111
Fig. 36:
Bachman Diagram
With the new CONTACTS table, there is an ambiguity in the resolution of the for each base table that we mentioned before. Now, there are two minimum extended tables that contain the For Each SupNam and AnlNam attributes: the one that has ORDERS as base table and the one that has CONTACTS as base table. But we want to list the names of the supplier and analyst of each order, and not each contact between them. To solve the ambiguity, we use the DEFINED BY clause within the FOR EACH command, Therefore, we will add the following in the example: For each DEFINED BY OrdDat print NameSupplierAnalyst Endfor The DEFINED BY clause must reference at least one attribute of the desired base table. Even if the problem mentioned above does not occur, we recommend using DEFINED BY clauses in complex reports, as it reduces the specification time.
Reports with several FOR EACH commands
Nested FOR EACHs

Until now we have defined reports with only one FOR EACH, but its possible to use more than one FOR EACH to make more sophisticated reports. Suppose you want to list the orders by supplier. For example:
Page 58 of 111
Fig. 37: ORDERS list by Supplier
For this, we create a report with the following Layout:
Fig. 38: Layout of the ORDERS list by Supplier
And we will write the following in the Source: Header print Header end For each print Supplier For each print ORDERS endFor print EndSupp endfor There are two nested FOR EACHs in this report. If you analyze the first FOR EACH, youll see that only the SupCod and SupNam attributes are used. Therefore, the extended table will be the SUPPLIERS table. The second FOR EACH uses the OrdNum, OrdDat, and OrdTot attributes, so its extended table will be ORDERS. But the second FOR EACH is nested in the first one, and the ORDERS table is subordinated to SUPPLIERS through SupCod. Thus, GeneXus will interpret the report as follows: Page 59 of 111
Desinging Applications in GeneXus For each record in table SUPPLIERS .... For each record in table ORDERS with the same SupCod .... endfor .... endfor In this way, for every record in the suppliers table all its orders in the orders table will be listed. When there are two nested FOR EACH statements, GeneXus looks for the subordinate relationship between the base table of the second FOR EACH and the extended table of the first FOR EACH. In the previous case, the relationship was that the ORDERS table was subordinated to the SUPPLIERS table through SupCod. This is how it sets the condition that the records of the second FOR EACH must fulfill (In the example, all the records of the ORDERS table with the same SupCod read in the first FOR EACH). There is one more case in which GeneXus finds a relation between the data to be retrieved. Lets say that we add a Countries transaction to the application, and then we represent that each supplier belongs to a country. The following Bachman diagram represents the relations between the relevant tables. ORDERS SUPPLIERS COUNTRIES by country, we will write the following
If we are interested in making a list of the ORDERS in the Source: For each print Country For each print Order endfor endfor
where Country is the name of a print block containing the COUNTRIES attribute (such as code and country name) and Order is the name of a print block containing the ORDERS attributes (such as OrdNum, OrdDat and OrdTot) Here, the base tables will be COUNTRIES and ORDERS respectively, and GeneXus finds that there is a kind of indirect subordination between them, so that for each record of the first for each base table, it will retrieve only those ORDERS corresponding to a supplier of this country from the second for each base table. Formally, this case occurs when the first for each base table is contained in the second for each extended table. But GeneXus might not find a relation between both FOR EACHs, for example in the following case:
Page 60 of 111
Desinging Applications in GeneXus For each print SUPPLIERS For each print Analysts endfor endfor where the Layout contains the following print blocks:
Fig. 39: Layout of SUPPLIERS and Analysts list
The base table of the first FOR EACH is SUPPLIERS (because the attributes are SupCod and SupNam). The base table of the second FOR EACH is ANALYSTS (because the attributes are AnlNum and AnlNam). There is no relationship between the extended table of SUPPLIERS and the base table of the nested FOR EACH: ANALYSTS. And the nested FOR EACH extended table does not contain the main for each base table either. In cases like this, where GeneXus does not find a subordination relationship, it uses the Cartesian product between both FOR EACH statements: For every record of the SUPPLIERS table, all the records of the ANALYSTS table will be printed.
Control Breaks
Control breaks are a special case of nested FOR EACH statements. Suppose you want to list the orders by date:
Fig. 40: ORDERS list by Date
Page 61 of 111
Desinging Applications in GeneXus The layout will be the following:
And the Source: header print Header end for each order OrdDat print Date for each print Orders endfor endfor
Fig. 41: Layout of the ORDERS list by Date
The base table of the first FOR EACH is ORDERS (because the only attribute appearing is OrdDat), which is also the base table of the second FOR EACH (because it has OrdNum and SupNam). This is an example of control break in the ORDERS table. GeneXus indicates it in the Navigation List with the word BREAK instead of FOR EACH for the nested For Each. Control breaks can have many levels; for example, if you want to list the orders by date and each date by supplier: For each order OrdDat .... For each order SupCod .... For each .... endfor endfor endfor When defining control breaks, its VERY IMPORTANT to indicate the ORDER in the FOR EACH statements, as this is how GeneXus knows through which attributes the control break is being made.
Page 62 of 111
Parallel FOR EACH statements

You can also define parallel FOR EACH statements. For example, if you want to include the suppliers and then the analysts in the same list you implement the following Source:
Fig. 42: Source of the SUPPLIERS and Analysts list
Where the Layout is:
Fig. 43: Layout of the SUPPLIERS and Analyst list
The lists with parallel FOR EACH statements are very useful, for example, to List all the information available about a Supplier. The Source will be: For each ... //Information about the Supplier For each .... // Information about Orders Endfor For each .... // Information about Prices Endfor Endfor
Page 63 of 111
Other commands
In addition to the commands already seen, other commands can be used in the Source. Youll see some of the most important ones here.
Defining Variables
Before describing the commands, lets revise the concept of Variable. Data is stored in the database in Attributes, but many times its necessary to use variables. The difference with Attributes is that they are local to the object where they are defined, and are not stored in the database. GeneXus recognizes a variable because its name starts with &, for example, &Today or &Aux. There are some predefined variables that have their own meaning. For example, we have already mentioned &Today, a variable with todays date. Another example is the variable &Page, which indicates the page being printed, etc. In addition to these system variables, the analyst may define his own variables for each object. These variables will be local to the object where they are defined. For each variable defined by the analyst, he must specify its characteristics, such as name, description, data type, length, decimals, etc. The following dialog is displayed for this:
Fig. 44: Variable Definition Dialog
Variables can also be defined in relation to other Attributes, using the Based on Attribute option appearing in the combo associated to the domain. . Its advisable to use this option whenever possible. In this way, whenever the data type of an attribute on which a variable is based is changed, the change is automatically transferred to the variable.
Page 64 of 111
Allocation
There are several commands (=, +=, -=, *=, /=) that allow allocating values to variables (in procedures, it is also possible to allocate values to attributes, as we will see later). For example, if we want to show totals on a list:
Fig. 45: ORDERS list by Date of execution
The Layout is the following:
Fig. 46: Layout of the ORDERS by Date report
Page 65 of 111
Desinging Applications in GeneXus And in the Source we will have: header print Header end &TotGen = 0 for each order OrdDat &TotDat = 0 print Date for each &TotDat += OrdTot print Orders endfor print TotDat &TotGen += &TotDat endfor print TotGen
Control Commands
Some control commands are the well-known ones If-else-endif and Do while-enddo. The Ifelse-endif command is very used for conditional printing; that is to say, printing a line only when a condition is matched. Example: if we want to print ORDERS by date, without totals, but we also want to show the quantity of ORDERS that exceed the total amount of $2000, we add the &Qty variable and write the following in the Source: &Qty = 0 for each order OrdDat print Date for each print Orders if OrdTot >= 2000 &Qty += 1 endif endfor endfor print Quantity where Quantity will be the name of a print block that will contain the Note that here, we do not use the else clause of the if command. &Qty variable.
The Do while-enddo command is very used to print several copies, for example, if we want to print two copies of an order. For each order OrdNum &i = 0 Do while &i < 2 &i += 1 // print order enddo endfor Other control commands are: Do case, For to Step, For in Array, For in Collection. Page 66 of 111
Calling other Programs and Subroutines

The call command can call another program, which may be another GeneXus program or an external program. The format of the command is: Call(Program_name, Parameter1, ..., ParameterN) Where Program_name is the name of the program called and Parameter1 to ParameterN are the parameters sent. These parameters can be Attributes, Variables and Constants, and they can be updated in the program that is called. When a Report is called from another Report that is also being printed, its important to pass as parameter the predefined variable &Line. This variable contains the line number that is being printed so that the called Report doesnt start in a new page. From the report main code, the Do command calls a subroutine that must be defined through the Sub command at the end of the report. In this case the parameters are not necessary, as the same data (variables) that are available where the Do is made are also available for the subroutine. Thus, you will have the following in the Source: .... DO 'Name-Sub-routine' .... Sub 'Name-Sub-routine' .... EndSub
Print if detail
Lets go back to the list of Orders by Supplier that we have seen before, and whose Layout we showed in fig.38. In the Source, we had the following For Each command: For each print Supplier For each print Orders endFor print EndSupp endFor The first For Each had SUPPLIERS as base table, since in the print block Supplier there were the SupCod and SupNam attributes and the second For Each had ORDERS as base table, since there were OrdNum, OrdDat and OrdTot. The first For Each is independent from the second, so the data of the first For Each will be printed BEFORE determining if there is related data in the second level. For this reason, ALL the suppliers will be printed, whether they have orders or not. If this is not what we want, that is to say, if we want to print ORDERS by supplier but only for those SUPPLIERS that actually have ORDERS, we can use the Print if detail command:
Page 67 of 111
Desinging Applications in GeneXus For each order SupCod Print if detail print Supplier For each print Orders endFor print EndSupp endFor This command states that the For Each in which it is located should use the same base table as the next For Each. In the example above, the first For Each will be based on the ORDERS table instead of the SUPPLIERS table. Therefore, only the Suppliers that have Orders will be printed. Note that as both For Each statements are now based on the same base table, a control break is implicitly defined. Therefore, the ORDER in the first FOR EACH MUST be explicitly defined. There are other commands such as EJECT (skips a page), NOSKIP, and so on.
Conditions
Global conditions (global filters) to be applied on the data to be retrieved are defined in this report section.These conditions are equivalent to the WHERE clause used in the FOR EACH command, and they even have the same syntax. The difference is that WHERE is applied only to the FOR EACH where it is located, and the conditions defined here will be applied to ALL the corresponding FOR EACH statements. The FOR EACH statements to which they are being applied are indicated in the Navigation List. Conditions generally dont have fixed values, and users are required to select the values when executing the Report. For example, if in the report listing the system SUPPLIERS we want to list a range of suppliers instead of all of them, we can specify the following conditions:
Fig. 47: Session Conditions of the SUPPLIERS list
When the report is executed, the following screen will be displayed:
Fig. 48: Screen to enter the SUPPLIERS range for the list
Page 68 of 111
Desinging Applications in GeneXus The range of Suppliers is accepted here. The value entered by the user is stored in the variables &ask1, &ask2 and so on, according to the order of appearance of the ask() in the conditions. These variables are useful to print the entered values.
Rules
Rules are used to define general characteristics of the list. Some of the Rules for Reports are:
Default
It allows defining default values for report variables. We can define, for instances, default values for ask: default(&ask1, 1); default(&ask2, 9999); The variables &ask1 and &ask2 must be defined and the order (1, 2, ) is the order in which conditions were defined.
Parm
Parm is a list of attributes or variables received as parameters by the Report. For example, if a Report is created to print an order immediately after entering it, the following rule is stated in the Orders transaction: call( RImpRec, OrdNum ) On AfterComplete; And the report will be: Source: For each print OrderHeader .... For each print OrderLines .... endfor endfor Rules Parm(OrdNum);
When an attribute is received in the Parm rule, it is automatically taken as a condition (filter) on the data to be recovered. In the example, as OrdNum is received as parameter the implicit condition for the first FOR EACH (based on the ORDERS table containing OrdNum) is that OrdNum must be equal to the value received in the parameter, and it is not necessary to add a WHERE. Otherwise, if the parameter were a variable, then it would be necessary to add a WHERE. Source: For each WHERE OrdNum = &Order print OrderHeader .... For each print OrderLines .... endfor endfor Page 69 of 111 Rules: Parm(&Order);
Report Wizard
he Report Wizard for the creation of reports is aimed at making this task easier and faster. This wizard is automatically displayed on creating a new report, and the analyst can cancel it if he prefers making all the operations manually, without help. The wizard is useful at the time of creating a report containing For Eachs, either nested or parallel. It allows designing the Layout and the Source in a quite easy way. It is defined based on a data structure very similar to the transactions structure. Lets design again the orders by supplier report. The layout design consists of two steps that will be explained below: Step 1: First, a data structure must be provided. Note that this structure should include attributes defined in the transactions. The data structure will use a syntax structure similar to the one used in the transactions; however, parenthesis are used to indicate the FOR EACH levels (instead of the transaction levels) and the asterisk (*) indicates the desired order (instead of uniqueness as in transactions). The rules that are used to define a transactions structure are also applied when defining this structure. The idea is that, for each level, a print block will be created in the Layout that will contain the attributes of this level and a for each in the Source that will send this print block to be printed in the output.
Fig. 49: Step 1 of the Report Wizard
To design the report, define a structure with the supplier data in the first level, and the order data in the second level. This will generate two nested FOR EACH statements where the external one will be ordered by supplier code. Once you have correctly defined the structure, press the Next button to go to the next step.
Page 70 of 111
Desinging Applications in GeneXus Step 2: This step allows specifying things such as if, for each level of the structure entered in step 1 we want to enter only the print blocks, only the code in the Source (for eachs and headers) or both things; or where we want to send the report output (the user decides in runtime if he will send it only to file, only to printer or only to screen),
Step 3: Allows defining some layout features. You can select the fonts for the attributes or labels, and you can also define whether the attribute headers in all levels will be displayed horizontally or vertically. This is the dialog box corresponding to step 3 for the data structure used in step 1:
As you can see, the level for which the layout type is being defined is marked with a different color. For that level, we leave its default type. and for the second level its necessary to make sure that the checkbox corresponding to the vertical layout is not selected. This way, the internal level display will be horizontal.
Page 71 of 111
Desinging Applications in GeneXus Step 4: This step allows specifying conditions for each level included in the report that will be translated in where clauses of the For Each corresponding to the Source level. For this, we must select the level and include the conditions applicable to this level. E.g.: if we do not want to print the SUPPLIERS with their ORDERS, but only those whose code is higher than 100:
The Finish button is for saving the settings of the current step and exiting the Report Wizard dialog. Once all the Wizard options have been accepted, the report Layout and Source are generated. They can be modified later like in any other report. In the example, after pressing Finish in the Wizard, the report is generated with the following Layout:
Fig. 53: Layout of the report generated with the Report Wizard
Here, there are 3 print blocks called P_Header, P_SupCod and P_OrdNum. To give a name to each print block of the Wizard structure, we use the prefix P_ followed by the first attribute appearing in the print block. A header is included, called P_Header, as we can see.
Page 72 of 111
Desinging Applications in GeneXus The Source of this report will appear initialized:
Fig. 54: Source of the report generated with the Report Wizard
Page 73 of 111
Properties
Like any other GeneXus object, reports also have properties that allow defining the general report behavior:
Fig. 55: Report Properties Dialog
Among the properties that we can define with the report properties editor, we have the following: Report Output: it allows specifying if the report output will be directly sent to screen, print or file or if the user must be asked about this in runtime. The possible options are the following: Ask User Only to File Only to Printer Only to Screen
Page 74 of 111
4. Dynamic Reports GeneXus Query

Dynamic reports allow end users to retrieve information directly from the database, without the need for technical skills and without requiring any additional development by analysts. Dynamic reports are made with GeneXus Query, an Excel Add-In that is automatically added to Excel when installing GeneXus Query. Users open Excel from the GeneXus toolbar and they can make their own queries by selecting the attributes to be queried, without the need for specifying the navigation or tables. The query result is returned in a pivot table or a query table within an Excel spreadsheet, allowing users to manage this information by leveraging the power of spreadsheets. When creating or reorganizing the database with GeneXus, the "metadata" is automatically generated, allowing users to dynamically make queries from Excel with GeneXus Query. Whats more, no additional development is required. Besides making queries, users can catalog and organize them in folders for later use, as well as chart them, publish the results on the Internet, define security settings for attributes and queries, and so on. Making queries To make a query, users open Excel and select the "New Query" option in the GeneXus Query toolbar. On the left side of the screen displayed, users can see the attributes that they are enabled to query 6 . Next, they select the attributes that they want to query, which are added to the right side of the screen.
Fig. 56: Query Invoice Detail by Customer
They can define their own folders in the attribute list, organizing the attributes that they use at their convenience, etc.
6
Page 75 of 111
Desinging Applications in GeneXus Users can change the function to be applied to the selected attributes. For example, they can calculate averages and percentages, count an attribute's values, and so forth. They can also limit the values to be shown in the query by adding filters to the query attributes (values list, complex conditions). Besides, they can set warnings by using colors to highlight those values that comply with certain conditions. Once the query is specified, it is executed and the result is displayed in Excel in the following way:
Fig. 57: Query result as Pivot Table in Excel
In the pivot table, users can manipulate the query data by pivoting, filtering values, defining formulas, drawing charts. Besides, they can catalog it, publish it on the Internet, and so on. Unlike the traditional Query Tools which require users to select table fields, and in some cases, determine how the "joins" should be made, GeneXus Query only requires them to select the attributes to be queried, and then it automatically determines the tables to be accessed, the navigation to be made, the restrictions to be applied, and so on. Whats more, it provides query catalog management, security at different levels, automatic impact on the metadata and the catalogued queries if changes are made to the database, and so on. The objective of GeneXus Query is to replace most of the reports of our applications, which are specifically designed and continuously developed, with dynamic queries. As a result, end users leverage their power and gain flexibility, while analysts are freed from the task of making custom reports.
Page 76 of 111
5. Procedure object
Procedures are the GeneXus objects used to define all the non-interactive processes that update the database, and the general subroutines. This object has all the features of a Report (any Report can be implemented as a procedure) and some specific features to update the database. It is recommended that you read the chapter Reports Object before starting this chapter. Lets see the procedure commands available to update the database:
Modifying data
Since there isnt a specific command to modify the data (such as REWRITE), the modification of data in the database is implicitly made. In order to modify the data, you must assign a value to an attribute within a FOR EACH and the modification will be automatically carried out. For example, suppose that you want to create a batch process that updates the ItemLstPurPrc attribute to adjust it according to the inflation rate, in all the stored items: Program: For each ItemLstPurPrc *= (1 + &Inf) endfor Rules: Parm(&Inf ); More than one attribute can be modified within the same FOR EACH. For example, if you also want to modify the attribute ItemLstPurDat, by setting todays date: For each ItemLstPurPrc = ItemLstPurPrc * (1 + &Inf) ItemPrcLstPur = Today( ) endfor The physical modification is not made immediately after each allocation, but in the endfor. In these two examples the Attributes of the FOR EACH base table were modified, but its also possible to update attributes of the tables (belonging to the extended table) using the same method used to assign attributes. Not all the attributes can be modified; for example, the attributes belonging to the primary key of the FOR EACH base table (in this case ItemCod) cannot be modified. The attributes of the index (order) used to access the base table cannot be modified either. If you want to update an attribute that is a candidate key, you must control the uniqueness of the new value. To understand this point better, lets review the observation that we made in the transactions chapter: if by any reason we leave as identifier of the 2nd level of the ORDERS transaction the OrdNum attribute instead of the ItemCod one, but we do not want repeated items in the lines of an order, we said that the possible solution was to define a UNIQUE type index made up by OrdNum and ItemCod (with this, we establish that OrdNum and ItemCod make up a candidate key). Now, lets say that the item of code 2 is no longer manufactured, and that there is a similar one, the 5. We must change the ORDERS so that we substitute the lines where item 2 was Page 77 of 111
Desinging Applications in GeneXus located by item 5. We would do as follows: For each Where ItemCod = 2 Defined by OrdQty ItemCod = 5 endfor But if for a given order there were lines with the two items, 2 and 5, when attempting to perform the allocation within the For Each, we will find that there was already a record with these values of OrdNum, ItemCod. But these values must be unique, and so this record will not be updated. If we want to execute an action when a candidate key is found duplicated, we use the for each WHEN DUPLICATE clause: For each Where ItemCod = 2 Defined by OrdQty ItemCod = 5 WHEN DUPLICATE Msg( There is already a line with this item) endfor In the Navigation List, the tables being updated are marked with a pencil icon. In the example where we update the price and date of the last purchase of an item, the Navigation List shows the following:
Fig. 58: Navigation list of Items updating procedure
Deleting data
The DELETE command in the FOR EACH-ENDFOR group is used to delete data. For example, if you want to eliminate all the orders dated earlier than a certain date: For each where OrdDat < ask('Delete orders with dates earlierthan:) For each defined by OrdQty // All the order lines are deleted DELETE endfor // The header is deleted after the lines DELETE endfor
Page 78 of 111
Adding data
The NEW-ENDNEW command is used to add new records to the database. For example, this is a procedure that receives AnlNum and AnlNam as parameters in the &Num and &Nam variables respectively, and then adds this data to the Analysts table: Program: New AnlNum = &Num AnlNam = &Nam Endnew Rules: Parm(&Num, &Nam ); This procedure can be used to add records to the Analysts table by using a subroutine. The NEW command performs a duplicate control both for the primary key and the candidate keys, and adds a record only if the table doesnt already have a record with the same primary key or candidate keys value. The WHEN DUPLICATE clause sets the action to take in case of duplicates. For example, in the previous case, to update the AnlNam if the analyst was already registered: New AnlNum = &Num AnlNam = &Nam When Duplicate For each AnlNam = &Nam endfor endnew Note that the assignments must be INSIDE the FOR EACH-ENDFOR group in order to modify attributes.
Integrity and redundancy controls

The only integrity control automatically carried out in Procedures is the duplicate control. On the other hand, the referential integrity is not automatically checked. For example, if you add a Procedure that automatically creates Orders, it wont check that the loaded SupCod already exists in the Suppliers table. Also, when deleting an order header you should remember to explicitly delete the order lines. The same rationale is applied to redundant formulas, which must be explicitly maintained with assign/update commands.
Page 79 of 111
6. Work Panel object

Work panels are used to make interactive queries to the database in Windows environment. Although this is an extremely versatile object that can be used for multiple purposes, it is especially useful for people who use computers to think or make decisions. The way work panels are programmed is inspired on the programming of graphic environments, especially event-driven programming.
Elements
For each work panel you may define: Form Like in transactions, we must define the form, which will be the interface with the user. But unlike transactions, work panels objects are only used in Windows environment; therefore, a work panel form is similar to a transaction GUI-Windows form. To program a Web screen for data querying, we will use the web panel object that we will mention later on. Events Define the response to the events that may occur during the work panel execution. For example, what actions should be triggered when users press Enter or a button. Conditions Define which conditions the data must fulfill in order to be displayed on screen. They are equivalent to the reports andprocedures Conditions. Rules / Properties Define general characteristics of work panels such as the parameters they receive, and so on. Help Text for helping users when using work panels. Documentation Technical text for use in the system documentation. Tabs to access elements Like in every GeneXus object, we can access several elements making it up using the tabs appearing at the bottom of the object editing window:
Fig. 59: Tabs appearing at the bottom of a work panel editing window
This chapter will only introduce the most outstanding features and uses of work panels. A more detailed description will be provided in the GeneXus course.
Example
In order to explain the use of this object type, a series of chained queries will be performed. These queries start with a Suppliers work panel where all suppliers are displayed and the users select one of them in order to perform an action related to it. In this case, for each selected Supplier you will be able to do the following: Page 80 of 111
Desinging Applications in GeneXus View the supplier's data View the supplier's orders We will call this work panel Working with SUPPLIERS, since this is just what we want: work execute some action- with SUPPLIERS. In runtime, the form will be visualized as follows:
Fig. 60: Form of Wording with SUPPLIERS in runtime
The codes and names of all system SUPPLIERS are shown in a grid. Then, the user may position the cursor on a line and execute an action with the corresponding supplier. If, for example if the user presses the View button on the supplier with number 125, it will display a window with this Supplier's data:
Fig. 61: Visualize a supplier data
Page 81 of 111
Desinging Applications in GeneXus Likewise, if you press the Orders button, the following screen, showing the Orders of this Supplier, will be displayed:
Fig. 62: Visualize the ORDERS of a supplier
This work panel could also be extended, allowing users to select a specific Order so as to view the items making it up, and so on. The actions that you saw in the first work panel apply to a line, but there are other actions that do not apply to any particular line, such as adding a new supplier. If this action is selected, by pressing the "Insert" button shown in the form, the Suppliers transaction takes charge in order to allow the addition of a new supplier.
Fig. 63: Insert new supplier
Refresh Button
It is automatically included by GeneXus in the form of every work panel. When you press it, all the grid lines are loaded again. As we will see later, there are several cases where it may be necessary to renew or refresh the loaded data. For example, when we add a new supplier to the system. Further on we will see this action in detail. Let's see how to define the first work panel of the example.
Page 82 of 111
Form
A work panel form is defined similarly to the GUI-Windows form of a transaction.
grid
Fig. 64: Form of the work panel: Working with SUPPLIERS
When adding a grid to the form (it is inserted like any other control, using the Controls tools palette) you are indicating that an indefinite amount of data will be shown in this case, Suppliers. Although you can simultaneously view only the lines on screen, GeneXus provides the mechanisms that users need to move around (called paginate) the list. The previous work panel has a grid whose columns correspond to the following attributes: SupCod and SupNam. Besides grids may contain attributes, variables and one or two dimensional array elements. Unlike transactions, these attributes will be output attributes, i.e.: they are used to show information of the database and the input variables (they are basically used to request information from the user).
Grid
The icon of the tool palette shown below enables you to insert a grid to the work panel form and define its characteristics, such as attributes and variables. These will make up the grid columns, the headers of these columns, and so forth.
Insert grid control
Fig. 65:
Controls tools palette for a work panel
Page 83 of 111
Desinging Applications in GeneXus Once the control has been inserted in the form, the following dialog box is opened where the following columns are specified:
Fig. 66: Control Grid Properties Dialog
The Name field is for naming the control, which will be useful later if properties, events or methods are associated to it. If you will include several grids within the form, you will have to identify them. Therefore, it is essential to allocate a value to this property for each one of the inserted grids. In order to select the Attributes and Variables that are going to be included in the grid, you should press the Add button. The Hide button enables us to hide the selected column. This is necessary when we do not want to show specific data on the screen, but we must have them loaded to be able to use their values later on; e.g.: if we select a line and want to execute some actions on it. The Move Up and Move Down buttons allow you to change the order in which the attributes will to be displayed in the grid. With the Column tab we can change the columns titles (by default, for an attribute, it takes the value of the attribute Title Column option; see figure 5, chapter 2), and if it is a no-scale variable, we can select the element of the variable that we want to use in this column, indicating row and column values. With the Colors and Fonts tabs you can change the colors and font size of the columns and the rows. With the Control Info tab you can select the type of control to be used for each grid attribute or variable. Once youve indicated a type, you should add the necessary information for that type. The available options are: Edit, Check box, Combo and Dynamic Combo (or the default one of the column's Attribute or Variable). The Advanced tab is for setting properties used for loading the grid. If they are not configured, the valid options for this grid will be the ones at object level, which appear under the "Loading" category in the properties dialog of the work panel, illustrated further on, in Fig. 77. Each column's width can be manually adjusted by unmarking the Auto Resize option. When this option is marked, GeneXus determines the column width by default according to the Page 84 of 111
Desinging Applications in GeneXus attribute or variable length and the column header. The Horizontal Scroll check box causes a horizontal scroll bar to appear in runtime, apart from the vertical scroll that appears automatically.
Events
The traditional way of programming the interface between the user and the PC (including four generation languages), is by subordinating the screen to the program. That is to say, from the program, we make calls to the screen. In work panels it is the opposite: the program is subordinated to the screen, since a screen makes calls to the program to give answers to an event. This working process is know as Event-Driven process and is typical of GUI (Graphic User Interface) environments, where it has already proven its productivity, basically because it only requires programming the answer to the events and not the repetitive task implied in the management of the whole interface. GeneXus version 7.5 introduces the possibility of creating several grids within the same work panel, something that wasnt possible in previous versions. Until this version, it was possible to show on screen only the data of a database table (and its extended one). Thus, if you wanted to list information of several different tables, you had to divide the information in different work panels. There are some differences between work panels that have only one grid and work panels with multiple grids, which are mainly related to the events and to determining the tables navigated to recover the data. This book deals with the first case, where the work panel has one grid, and the case about multiple grids will be dealt with in the GeneXus course. The events structure is summarized below: Start Start Event Refresh Event Load data to the SubFile from the database (one Load Event is generated for every record read) Show data on screen Enter Event 'User-Defined' Event Exit Event End
The same language that you saw in the chapter about reports and procedures is used for programming each event, but the print commands (Header, Footer) and the database update commands (New, Delete) are not allowed. There are also specific commands for work panels such as Refresh, Load, and so on.
Page 85 of 111
Start Event
The Start event occurs when the work panel is displayed. Example: Event Start &Date = &Today Endevent In this case, the Start event is used for updating the current date according to the &Date variable which, for example, will be displayed on screen. This technique is very useful to initialize default values, and above all, the complex ones (for example, &Value = udp('PX', ...)).
Enter Event
This event is triggered when the user presses ENTER (or the Confirm button). Lets say that in the work panel Working with SUPPLIERS we want to add the possibility of deleting a group of SUPPLIERS. We can implement this by defining a new column in the grid, made up by a variable, &op, where the user will enter the operation type he wants to execute on each line. Lets say that a value 4 in the &op variable means that you want to delete this supplier. We will program the Enter event so that we can scan the grid and, for each line with operation code 4, we can call a procedure to delete this supplier. The associated code will be: Event Enter For each line If &op = '4' Call(PDltPrv, PrvCod) else If &op <> ' ' Msg(concat(&op, ' this is not valid') ) Endif endif endfor endevent The Enter event is a bit more extensive, and should be studied in more detail. First, a FOR EACH LINE command is used to perform a FOR EACH, which is not performed on the database data but on the data loaded in the grid. The value of &op is queried for each grid line.If it is 4, the DltS up procedure is called. In any other instance the user will receive a message indicating that the option is not valid. Note that more options could have been defined and queried for this event.
Page 86 of 111
User-Defined Events
Fig. 67:
Insert Event in work panel Working with SUPPLIERS
This event was created by a user so it should be given a name; in this case, it is called Insert . It calls the Suppliers transaction, and after that the Refresh command is executed in order to reload the grid because a new supplier has been added and it must appear on the screen. This command could also have been used with the keep parameter (Refresh Keep), which causes the cursor to stay on the same grid line where it was before the command execution.
Refresh Event
The data displayed on screen is loaded in the grid from the database when the work panel is displayed. The interaction with the database occurs the moment the load is executed and then the user will work with the loaded data. In a multi-user environment, on-screen data may be old if it has already been modified from another user terminal. To update the data, the user should click the Refresh button (or press the F5 key) and the grid will be updated and reloaded. The Refresh event (system event) occurs during the second previous to the grid load. Immediately after it occurs, the database is accessed and the grid is loaded. Therefore, as a result of the Refresh event triggering, data are loaded and shown on the screen. In some cases, the grid has to be reloaded from another event, for example, when a transaction that updates the data showed in the grid is called in another event (this is the case of the Insert Event in the previous figure). For this, a Refresh command is provided, whose effect is triggering the event with the same name. The grid is loaded (i.e.: the Refresh event occurs) when: The screen is loaded there is always a Refresh event after the Start event. The user clicks the Refresh button (or presses the F5 key). The Refresh command is executed in another event. The user changes the value of a variable in the form fixed area. These variables are used as conditions on the data to be loaded (this will be seen later).
Page 87 of 111
Loading data to the work panel

As you saw in the events' diagram, after the Refresh event the grid is loaded with the data obtained from the database. In order to determine which tables the data must be obtained from, GeneXus uses the same mechanism described for the FOR EACH groups in the Reports chapter. But in this case there is no FOR EACH! However, it is considered that each work panel with a grid has an implicit7, FOR EACH with the following attributes: All the attributes displayed on the form (including the ones of the fixed area). All the Events attributes, except for those inside an explicit FOR EACH. All the grid attributes that are hidden, that is to say, those for which we pressed the Hide button of the General tab of the grid properties dialog. All the grid attributes that have been inserted on the Grid Order screen that is accessed through the Order option of the pop up menu displayed by right clicking on the grid, as we will see later on. With these attribute, GeneXus figures out the corresponding extended table, as it did with the attributes retrieved from a For Each. Then, it scans the base table and access the extended tables to retrieve the values of the attributes appearing in the grid, either visible or hidden, as it did with the print blocks within a For Each in a report. For each record found, the Load system event is generated. This way, the relationship between the Refresh event, the implicit FOR EACH and the Load event is the following: Event Refresh ... Endevent FOR EACH Event Load ... Endevent ENDFOR
The data that is read in this implicit FOR EACH is loaded in the grid, which is displayed on screen. This load is performed on request, so at the beginning only the first page is loaded, and as the user requires more information, the following pages are loaded. Note that there is a property for indicating that you want to load the whole grid at once, if necessary (the "Load Records" property). As in reports and procedures, the work panel Navigation List indicates the tables that are being used, the indexes and so on. It is possible that, although there is a grid in the form, there is not an implicit FOR EACH. This occurs when there is no attribute, neither in the form nor in the events outside the For Each, or at grid level in the Hide and Order options; that is to say, when in these places there are only variables.
7 As we will see later on, when mentioning the work panels without base table, not always do we find an implicit for each.
Execution
Page 88 of 111
Desinging Applications in GeneXus In this case only ONE Load event is generated (instead of one per each line to be loaded in the grid) and the data in the grid must be loaded there (using the Load command). In this case we say that there is a work panel without base table. Example: lets say that we want to implement a work panel where all the SUPPLIERS are shown and, for each of them, the corresponding ORDERS Total. We can do this using variables to load data in the grid:
Fig. 68: Form of the work panel Total by supplier
We program the following in the load event: Event Load For each &SupNam = SupNam &Total = 0 for each &total += OrdTot endfor Load endfor endevent Therefore, the Refresh event will occur, and then the Load event, only once. Each line is loaded in the grid with the Load command and the iteration is performed with the For Each programmed by the analyst. Depending on the implementation platform, we may keep the load on request feature or not for this case where there is not base table. In .NET and Java it is kept. Although in Visual Basic and Visual FoxPro, all the grid information is loaded before showing the data.
Page 89 of 111
Conditions
In this section we define the constraints established on the data to be retrieved, in the same way as in the reports. Whats interesting about the work panel conditions is that they can include variables displayed on screen, in such a way that the user can change the grid data by changing these variables, all without leaving the screen. For example, if you want to view only a range of suppliers, you should add &SuppIni and &SuppEnd variables to the form:
Variables to enter the initial and final supplier
Fig. 69: Form of work panel to work with SUPPLIERS within the range selected by the user
And define the conditions:
Fig. 70: Conditions to filter the SUPPLIERS shown in the grid
This way you obtain the desired effect. Note that each time the user modifies one of these two variables appearing in the conditions, the refresh event should be triggered to reload the grid. This is automatically done. All the considerations about optimizing conditions seen in the reports chapter are also valid here. Page 90 of 111
Data order in the grid

When in a report we wanted to sort a For Each by a specific group of attributes, we used the Order clause. In case of a work panel where we have an implicit For Each; where can we say that we want to retrieve the data in the grid in a specific order? E.g.: if we want to see the SUPPLIERS in alphabetical order, how should we specify the order? This is achieved by right clicking on the grid and selecting the Order option appearing on the displayed menu:
Fig. 71:Data order in the grid
A screen will be displayed that allows inserting the attributes by which we want to sort the grid (in this case we chose SupNam) This is equivalent to the ORDER clause of the FOR EACH and everything we said about this topic in the report object chapter applies here.
Rules
Most report rules are valid, in addition to some specific ones:
Noaccept
Unlike Transactions, work panels dont accept any attributes (their values are always shown but you cannot modify them). As for variables, the following is applied: All the variables displayed on screen are accepted, as long as they dont have the NOACCEPT rule. E.g.: in a work panel where we want to show the date in the form, having the date loaded in the variable &Date, we write the following rule so that the field value is not modified noaccept( &Date ); Page 91 of 111
Search
When a grid has many loaded lines , analysts often want to offer the user the possibility of directly going to a certain line, without having to advance page by page, scrolling. For example, to add the possibility of searching by supplier name in the Suppliers work panel you should define the rule: search( SupNam >= &Nam ); and add the &Nam variable to the screen:
Fig. 72: Form of Working with SUPPLIERS with the possibility of positioning on a given line
This way, each time the user enters something in &Nam, after pressing Enter, the cursor will remain positioned on the first supplier whose SupNam is longer than or equal to the one entered. In situations involving names, is the like operand is commonly used: search( SupNam LIKE &Nam ); The cursor is positioned on the first supplier whose SupNam contains &Nam (in the previous example, if X was entered in &Nam, it would go to Gx Corp.). Although this rule is very useful for the user to advance quickly in a grid, it is important to remember that there is no way to optimize it. If you want to use the optimizing criteria, you should use the conditions.
Page 92 of 111
Bitmaps
Bitmaps are usually used to enhance the appearance of applications. They can be added to the forms of transactions and work panels, as well as in reports and procedures layouts. GeneXus provides two different methods for adding a bitmap:
Fixed Bitmaps
You can add a bitmap control by selecting the corresponding item from the Controls toolbar. On inserting a bitmap control, a dialog is displayed to set up its properties. The most important one is the bitmap location, FileName. For example, a logo has been added to the work panel for viewing the Suppliers data. The new form will look like this:
Fig. 73: Work panel Visualize Supplier with fixed bitmap
In this case the same bitmap will always appear in the form, regardless of the supplier.
Dynamic Bitmaps
This method is different in that the bitmap is assigned to a variable, and that the desired bitmap can be loaded by using the Loadbitmap function. For example, you could have a Bitmap that shows each supplier's photograph. Definition of a bitmap type variable:
Fig. 74: Bitmap type variable definition
Page 93 of 111
Desinging Applications in GeneXus In the load event, the bitmap for the supplier passed as parameter should be loaded. To do this, you should add a SupPhoto attribute to the Suppliers transaction, which will contain the file location and type (.bmp, .gif, .jpg, and so on.) with the photo to be loaded.
Fig. 75: Load Event to load dynamic bitmap
In runtime, it will be displayed as follows:
Fig. 76: Visualize supplier in runtime with dynamic bitmap
Page 94 of 111
Properties
Fig. 77: Properties Dialog of work panel Working with SUPPLIERS
The properties appear grouped by categories. E.g.: Under the Loading category there are properties related to the work panel data loading. Among them, there is the Load Records property that allows specifying if the user wants to load the data in the grid while scrolling or if he wants to load all of them at the beginning. If there is a large volume of data to be loaded, the value of this property will produce a significant difference in response time. Although each grid has the possibility of defining the same loading properties, if a work panel has multiple grids and we want to specify the same properties in all of them, the simplest way of doing it is at object level, instead of doing it grid by grid. There are other properties related to the interface, which appear under the User Interface group.
Page 95 of 111
Object-Action Dialogs
Work panels allow designing applications with an architecture oriented towards the use of ObjectAction dialogs. But before introducing this concept, lets look at how it was traditionally done. If you observe an application developed with the traditional methods, you will see that the bigger the application, the bigger will be the menu tree used for accessing the programs that actually work with the data. Generally, this is the architecture of this type of systems:
Action Selection
Menus Trn Rpt

Apply the action to the object
This situation can be clearly seen in systems with many queries. In general, all these queries depend on a menu, but they are not chained to one another. Since they are not chained, the more queries are implemented in the system, the less they are used because users cant remember the differences between them. We will say that this type of application has an Action-Object dialog, because first you choose the action to be performed (for example, modifying a supplier or listing the orders) and then you select the object that the action will be applied to (which supplier or the orders of a certain date). By using work panels its possible to implement systems where the dialog is Object-Action, in which first you select the object that you are going to work with and then the actions that will be applied to it. In this case the architecture will be:
Menus Work Panels Trn Rpt
Object type selection Action and Object selection Apply the action to the object
This way, once users select the type of object that they are going to work with, they can immediately start using the Work Panel that allows them to select the object itself, and then, the actions to be applied to it. This architecture allows developing complex applications, which are nevertheless easy to use.
Page 96 of 111
GeneXus Browser
This browser allows, among other things, displaying all the model objects called through the call and udp commands as well as the prompts and themes. Given a program, you can see its call tree (which programs it calls) and from which programs it is called (by selecting the Call tree or Callers tree option of the browser dialog). In this example you will see the call tree of the work panel Working with SUPPLIERS. For this, we select the option Tools/Browsers from the GeneXus menu and then we select the object whose information we are interested in visualizing with the Pattern option:
Fig. 78: Browser Call tree
From this browser you can edit any object that appears in the lists.
Page 97 of 111
7. Web object
Web Objects are used for developing Internet applications. They generate HTML code (the code interpreted by browsers) and can interact with the database, allowing you to generate dynamic web pages besides generating static pages. Web Objects can be classified in two groups: Web Form Transactions (HTML) and Web Panels. Their development is immediate, since any GeneXus user will work with Web Objects in the same way as with other GeneXus objects, thus reducing development times. This topic will not be covered in detail in this book; however, a brief description is included below.
Transactions
Web transactions are not a new type of GeneXus objects; they are another transaction form that can be executed in a browser. To design the Web form (HTML) of a transaction, you should open the transaction and select the Object/Web Form option of the GeneXus menu or the tab labeled as Web Form. Web Transactions make Web applications design easier: as you enter data, it automatically performs all the required referential integrity controls. To execute them, the only requirement is a browser installed in the client.
Web Panels
It could be said that Web Panels and Work Panels are similar, since both allow submitting interactive queries to the database. Besides, they are very flexible objects that can be used for several purposes, and their programming is event-driven. However, there are some differences between them, mainly caused by the way of working on the Internet. A very important difference between these two objects is that in Web Panels, the query result is formatted in HTML at execution time to be shown in a browser.
Page 98 of 111
Appendix A. Relational Data Models

The purpose of this Appendix is to explain some relational database concepts which are relevant to use GeneXus.
Tables
In a relational database, the only way to store information is in tables. A table is a matrix with rows and columns, which has a name associated to it . Columns will be called attributes, and rows will be called records or tuples. For example: SUPPLIERS SupCod 125 126 SupNam ABC Inc. GX Corp. SupAddr 18 de Julio 1213 Br. Artigas 980
A table is different from a conventional file due to the following rules: All the attributes represent the same information for every row (or record). That is to say, all Supplier names are stored in the SupNam attribute, and it is not possible to include their addresses in the same attribute. In practice, this rule means that there arent any tables with different types of records. There are no two records with exactly the same information. The order of the records does not contain any information, which means that they can be reordered without losing any information.
Primary Key and Candidate Keys

As there cannot be two records with the same information in a table, you can always find the attribute or set of attributes which values are not duplicated. This attribute or set of attributes is called table primary key. In fact, there may be several of those sets, and each one is called candidate key. For example, if there cannot be two suppliers with the same code, and there cannot be two suppliers with the same name, in the Suppliers Table, SupCod and SupNam will be candidate keys. In a relational database for the entire table we must define one of the candidate keys as primary key. Besides, the following rule must be matched: there cannot be two tables with the same primary key. Let's consider the following design: SUPPLIERS SUP_ADD
SupCod SupCod SupNam SupAdd
Page 99 of 111
Desinging Applications in GeneXus The SUPPLIERS table and the SUPADD table both have the same primary key8 :the SupCod attribute. This was fairly common when the design rationale was to separate the updates: since SupAdd changes more often than SupNam, it is better to create a different file where the record that is modified is smaller and with better performance. However, in a Relational Database the design criteria is different (see the Normalization section) and it is advisable to have only one table with the three attributes: SUPPLIERS
SupCod SupNam SupAdd
Referential Integrity
These are rules about the consistency of the data stored in different tables. Suppose that this data model is the representation of a Purchasing System for a Pharmacy Chain, introduced in chapter 1. In this system, we want to represent item orders placed with suppliers by purchase analysts. For this, we will need an ORDERS table with information on the orders made by purchasing analysts to the suppliers. This table may contain the following attributes: OrdNum, OrdDat, SupCod, AnlNum, and OrdTot to represent the order number, its date, the supplier receiving the order, the purchasing analyst who made the order and the order total amount, respectively.
ORDERS
OrdNum
OrdDat
SupCod
AnlNum
OrdTot
If we observe the two tables: the previously defined SUPPLIERS table and the ORDERS table, we see that they have an attribute in common: SupCod. With this we want to indicate that the information of both tables is mutually related, since there is the same SupCod in both tables. So, we use the foreign key concept (FK: Foreign Key). We say that SupCod is a foreign key (FK) in ORDERS to the SUPPLIERS table (which has SupCod as primary key). With this we mean that we cannot enter any given value for a record of the ORDERS table in the SupCod (ORDERS.SupCod) attribute: this record must match the condition that there must be a record in the SUPPLIERS table for which: SUPPLIERS.SupCod = ORDERS.SupCod In other words: the supplier must exist.
ORDERS
OrdNum
OrdDat
SupCod
FK
AnlNum
OrdTot
SUPPLIERS
SupCod
SupNam
SupAdd
The relation between SUPPLIERS and ORDERS can be also represented through the following diagram, inspired in the well-known Bachman Diagrams:
To represent the primary key of a table, we draw a line under the attributes making it up.
Page 100 of 111
Desinging Applications in GeneXus Usually, in relational data models, the foreign keys of each table must be explicitly established. In GeneXus, this is implicitly done: the relationship between these two tables by analyzing the attributes that they share. Here the attribute in common is SupCod, which is the Primary Key of the SUPPLIERS table and is included in the ORDERS table. Therefore, both tables are related, and the relationship is 1-N. A 1-N relationship indicates that a Supplier may have several associated Orders and that an Order can have only one Supplier. Also, it is commonly said that the SUPPLIERS table is superordinated to ORDERS, and that ORDERS is subordinated to SUPPLIERS. This relationship implies that the data from both tables is not independent and that every time you modify one of the tables you must take into account the data of the other table. These constraints are called Referential Integrity: When a record is deleted from the superordinated table (SUPPLIERS), there shouldnt be any associated records (making a reference to it) in the subordinated table (ORDERS). When records are created/modified in the subordinated table (ORDERS), the corresponding record (referred to) must exist in the superordinated table (SUPPLIERS). Bachman Diagrams clearly illustrate data models referential integrity relations.
Indexes
They are efficient access paths to tables. There are four types of indexes in GeneXus: Primary, Foreign, User-Defined and Temporary. At the same time, the User indexes may be Unique or Duplicate. The Primary Index of a table is the one defined for the primary key. It is used to check the uniqueness of records. Whats more, the existence of the primary index makes it possible to efficiently perform the second referential integrity control seen on the previous page. In that example, the SupCod index in the SUPPLIERS table allows to efficiently check that, when entering/modifying a record in the ORDERS table, there is also one in the SUPPLIERS table; the value of the SupCod attribute stored in the first record should match that of the attribute with the same name, which is stored in the second record. GeneXus automatically defines all the primary indexes from the transaction identifiers. Foreign Indexes are used to efficiently check inter-table integrity. They are defined for foreign keys and therefore they make it possible to carry out the first referential integrity control previously mentioned. In this example, the existence of the foreign index for SupCod in the ORDERS table allows an efficient control, based on which it forbids the deletion of a record from the SUPPLIERS table if there is one in the ORDERS table: ORDERS.SupCod = SUPPLIERS.SupCod. This prevents from leaving loose references. GeneXus automatically defines all foreign indexes from foreign keys that, as we previously mentioned, are identified by GeneXus based on the attribute names. If these two index types are not defined, the referential integrity control system, which is essential to ensure the consistency of the data, would be awfully inefficient. This is the reason why GeneXus creates and maintains these indexes automatically. On the other hand, user indexes are not automatically created by GeneXus. They are created at the request of the analyst and are basically defined to retrieve data efficiently in a Page 101 of 111
Desinging Applications in GeneXus specific order. E.g.: in the SUPPLIERS table, we can define a SupNam index that is quite useful for the SUPPLIERS lists sorted by name. The candidate keys for a table (different from the primary key) are defined in GeneXus through the creation of user indexes. When a candidate key is defined in GeneXus, the latter controls the uniqueness of the values of the attributes making it up in the same way as it does for primary keys. To be able to perform this control efficiently, GeneXus must create an index; therefore, candidate keys are directly defined through the creation of a user index specifying that the values must be unique. Therefore, user indexes allow specifying that values will be Unique or Duplicate Lastly, Temporary Indexes are created in some implementation platforms to efficiently read a table in a certain order without creating a user-defined index for this. In this case an index is created on a temporary basis, and after being used, it is deleted. Temporary indexes are also automatically created by GeneXus. In a relational database, indexes are used only for performance reasons but it is always possible to access a table data by using any of its attributes.
Normalization
The normalization process determines in which tables reside each one of the database attributes. The idea is to define the database structure in such a way that the possibility of inconsistency is reduced to a minimum. For example, in order to store information about suppliers and orders, the following structure could be used:
ORDERS OrdNum OrdDat SupCod
FK
SupNam
AnlNum
OrdTot
SUPPLIERS
SupCod
SupNam
SupAdd
Both tables have two attributes in common (SupCod and SupNam). As for SupCod, it has to be in both tables because it is the SUPPLIERS identifier, and therefore it must be both in the SUPPLIERS table as primary key and in ORDERS as foreign key, so as to indicate which supplier the order corresponds to. The situation is different for SupNam. It is not necessary for it to be in the ORDERS table, because if you know the supplier code, SupCod, you can determine its name, SupNam, just by looking for it in the SUPPLIER table through the Primary Key. If the SupNam was stored in the ORDERS table the structure would have more inconsistencies than if it wasnt there. For example, if a supplier changes its SupNam, the developer is responsible for having a program that reads all the orders of that supplier and assigns them the new SupNam. The correct structure (we will call it normalized) will be:
ORDERS OrdNum OrdDat SupCod FK SUPPLIERS SupCod SupNam SupAdd AnlNum OrdTot
The normalization process,which has been informally explained, is based on the concept of Page 102 of 111
Desinging Applications in GeneXus functional dependency, whose definition follows: An attribute is said to functionally depend on another if for each value of the second one there is only ONE value
For example SupNam functionally depends on SupCod because for each value of SupCod there is only ONE value of SupNam. The definition is a bit longer, as it states that a set of attributes can functionally depend on another set of attributes. GeneXus designs the database taking it to third normal form (admitting some exceptions). For a more detailed study of normalization, refer to any book dealing with the relational data model.
Extended table
As it was explained in the previous section, the database design rationale is based on minimizing the possibility of inconsistent data. A database that has been designed in this way offers significant advantages (data normalization is a design standard), but we must take into account some of its disadvantages. The most obvious disadvantage is that the data is distributed in many tables, meaning that to make complex queries to the database all the tables must be queried. For example, in order to list the Orders by Supplier it is necessary to query both the SUPPLIERS and ORDERS tables. To simplify this task, GeneXus uses the extended table concept, whose definition follows: Given a database table that we will call base table, its so-called extended table is made up by the group of attributes that: belong to the table, belong to the entire Y table, so that the relation between the so far determined extended table and the Y table is N-1.
This is a Bachman diagram of the data model corresponding to the purchasing system for the pharmacy chain introduced in chapter 1:
Page 103 of 111
Besides the suppliers and orders tables, there are three more: ITEMS, to store the information about the items, ANALYST, to store the information about the purchasing analysts, and ORDERS1, which records the order lines, that is to say, the items making up each order together with the item price and the total amount ordered. As you can see, the ORDERS extended table involves all the attributes of the Orders table, plus all the attributes of SUPPLIERS and ANALYSTS, except for the attributes of the Order Lines, ORDERS1, or ITEMS (although they are related, their relation is not N-1). The following diagram shows the extended table for each of the model tables: Base table SUPPLIERS ANALYSTS ORDERS ORDERS1 Extended table SUPPLIERS ANALYSTS ORDERS, SUPPLIERS, ANALYSTS ORDERS1, ORDERS, SUPPLIERS, ANALYSTS, ITEMS ITEMS
ITEMS
The concept of extended table is widely used in GeneXus, where we usually work with extended tables instead of physical tables. For example, the FOR EACH command that we will study determines an extended table and not a physical one. The same happens with the transactions, where any attribute belonging to the extended table corresponding to the transaction level we are working with, can be directly updated by means of the rules.
Page 104 of 111
Appendix B. Functions, rules and commands

The following tables list some of the available functions, rules and commands: FUNCTION DATE MANAGEMENT Day Month Year Today DoW CdoW CMonth CtoD DtoC YMDtoD Addmth Addyr Age Eom STRINGS MANAGEMENT Str Substr Concat Space Len Trim Ltrim Rtrim Upper Lower Int Round Val DESCRIPTION A date's day number A date's month number A date's year Today's date The weekday's number of a date (1..7) A weekday's name of a date A date's month name Converts a character type to date type Converts a date type to character type Assembles a date from year, month and day Adds a given number of months to a date Adds a given number of years to a date Difference in years between two dates Last date of the month
Converts a numeric to string A string's substring Concatenates two strings Defines a string with n blanks A string's length Removes blank characters from a string Removes blank characters at the beginning of a string Removes blank characters at the end of a string Turns a string into uppercase Turns a string into lowercase Integer part of a number Rounds up a numeric value Converts a string to numeric
Page 105 of 111
Desinging Applications in GeneXus OTHERS Old Previous Time Systime Sysdate Userid Usercls Wrkst Ask Udf Udp Null( <Att|Var> ) Nullvalue( <Att|Var> ) LoadBitmap RGB (<R>,<G>,<B>) Color(<GXColor>) Random() Reseed
Attribute value before being modified Attribute value in the last insertion Time System's time System's date User identification User Class Workstation To ask for values on screen User-defined function User-defined procedure If an attribute has a null value or not Returns an attribute's null value Loads a bitmap Returns the number representing the RGB color determined by the three parameters Returns the number representing the color passed as a parameter Allows to generate random numbers Sets the seed for the Random() function
WHEN RULES ARE TRIGGERED IN TRANSACTIONS After(Insert) After the record is inserted After(Update) After the record is updated After(Delete) After the record is deleted AfterValidate After the record is confirmed (it hasnt been modified yet) AfterComplete After a cycle of the transaction is completed (after COMMIT) After( <Att> ) Function that returns true after the specified attribute. After Level After the level of the mentioned attribute is iterated in the Level clause following it. If no Level clause follows, it is the first level. Level <Att> A transaction's level Modified() Returns true if an attribute of a certain level is modified If the transaction is in insert mode Insert Boolean function If the transaction is in update mode Update Boolean function If the transaction is in delete mode Delete Boolean function
Page 106 of 111
Desinging Applications in GeneXus RULES Default Equal Add Subtract Serial Msg Error Noaccept Call Submit Parm Nocheck Allownulls Refcall Refmsg Prompt Noprompt Accept Default_mod e Color Order Search Hidden Noread Printer DESCRIPTION Gives a default value to an attribute or variable. Assigns a value in insert mode and works as a filter in update and delete Adds a value to an attribute taking into account the transaction's mode Subtracts a value from an attribute taking into account the transaction's mode Numbers the attributes Displays a message Error Rejects an attribute or variable on screen Calls a program Submits a call to a program To receive parameters Doesnt perform the referential integrity check Allows to enter null values Performs a call when the referential integrity check fails Message that is displayed when the referential integrity check fails Associates a user-defined object to the prompt Inhibits the selection list Accepts attribute or variable on the screen Mode by default when opening a transaction Gives colors to the attributes, variables and background Order of the Work Panel's base table Condition for searching the subfile To include variables or attributes in the subfile Inhibits the reading of attributes To select the printer file on iSeries or the printing form in other generators. R = Reports P = Procedures T W R P
T = Transactions W = Work Panels
The marked boxes indicate that the function is available for that object.
Page 107 of 111
Desinging Applications in GeneXus COMMANDS Header Footer For each For each line [IN] Exit Do while For to Step DESCRIPTION Header's start Footer's start To read the records in a table To read the subfile lines T WR P
Allows to exit a WHILE Repetition of a routine while a condition is fulfilled Iterates a certain number of times, starting from a certain value up to a specific value with a given increment. Executes a block according to the condition that is fulfilled Executes a command block if the condition evaluates to true Commit Rollback Prints if there are records in the subfile Ends the execution and returns to the caller program A variable's assignment Number of line where the data will be printed Sends special commands to the printer Page length Top margin Inserts a page break if there are less than n lines to be printed Doesnt jump to the following printing line Page break Calls a program Submits a program Displays a message Calls a subroutine Subroutine block Attribute updating Inserts a record Deletes a record
Do Case If Commit Rollback Print if detail Return &<a> = <Exp> Lineno Prncmd Pl Mt Cp Noskip Eject Call Submit Msg Do Sub - EndSub ATT = <Exp> New - EndNew Delete
Page 108 of 111
Figures Index
Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. 1: Tabs at the bottom of the transaction editing window .................................................13 2: Suppliers transaction structure .............................................................................14 3: GUI Form of the Suppliers transaction ...................................................................14 4: Web Form of the Suppliers transaction...................................................................15 5: Define Attribute Dialog ........................................................................................16 6: Orders transaction structure in GeneXus ................................................................23 7: GUI Form - SUPPLIERS transaction........................................................................27 8: Default GUI Form of the ORDERS transaction..........................................................28 9: SUPPLIERS Selection List .....................................................................................29 10: Items transaction form ....................................................................................31 11: Customized form of the ORDERS transaction.........................................................33 12: Controls Tools Palette .......................................................................................33 13: Form Editor Tools Palette ..................................................................................33 14: Control attribute/variable Properties......................................................................34 15: Control Text Properties.........................................................................................36 16: Rectangle control properties..................................................................................36 17: Control Properties Selection Dialog.........................................................................37 18: Bachman Chart: ORDERS and ORDERS1 tables........................................................39 19: Browser: Purchase System ...................................................................................40 20: Formulas in the ORDERS transaction structure ......................................................41 21: Transaction Properties Dialog ................................................................................46 22: Tabs appearing at the bottom of the report editing window........................................47 23: Suppliers list in runtime........................................................................................48 24: Layout of the Suppliers list .................................................................................48 25: Print Block Control Properties ..............................................................................49 26: Controls Tools Palette in Reports .........................................................................49 27: Source of the SUPPLIERS list ..............................................................................50 28: ORDERS list in runtime ......................................................................................51 29: ORDERS list Layout ...........................................................................................51 30: Model Bachman Diagram ......................................................................................52 31: Navigation list of the ORDERS list report ..............................................................52 32: Fragment of the navigation list of the ORDERS list report........................................53 33: Navigation list of the ORDERS list report sorted by date........................................54 34: Fragment of navigation list of optimized for each .....................................................55 35: Fragment of navigation list of non-optimized for each ...............................................56 36: Bachman Diagram .............................................................................................58 37: ORDERS list by Supplier .......................................................................................59 38: Layout of the ORDERS list by Supplier..................................................................59 39: Layout of SUPPLIERS and Analysts list....................................................................61 40: ORDERS list by Date ............................................................................................61 41: Layout of the ORDERS list by Date ......................................................................62 43: Layout of the SUPPLIERS and Analyst list .............................................................63 44: Variable Definition Dialog......................................................................................64 45: ORDERS list by Date of execution .........................................................................65 46: Layout of the ORDERS by Date report ..................................................................65 47: Session Conditions of the SUPPLIERS list ...........................................................68 48: Screen to enter the SUPPLIERS range for the list .....................................................68 49: Step 1 of the Report Wizard ..................................................................................70 50: Step 2 of the Report Wizard ..................................................................................71 51: Step 3 of the Report Wizard ..................................................................................71 52: Step 4 of the Report Wizard ..................................................................................72 53: Layout of the report generated with the Report Wizard .............................................72 Page 109 of 111
Desinging Applications in GeneXus Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. Fig. 54: Source of the report generated with the Report Wizard .............................................73 55: Report Properties Dialog .......................................................................................74 56: Query Invoice Detail by Customer .......................................................................75 57: Query result as Pivot Table in Excel........................................................................76 58: Navigation list of Items updating procedure.............................................................78 59: Tabs appearing at the bottom of a work panel editing window....................................80 60: Form of Wording with SUPPLIERS in runtime........................................................81 61: Visualize a supplier data .......................................................................................81 62: Visualize the ORDERS of a supplier ........................................................................82 63: Insert new supplier ..............................................................................................82 64: Form of the work panel: Working with SUPPLIERS .................................................83 65: Controls tools palette for a work panel ..............................................................83 66: Control Grid Properties Dialog ...............................................................................84 67: Insert Event in work panel Working with SUPPLIERS .........................................87 68: Form of the work panel Total by supplier ..............................................................89 69: Form of work panel to work with SUPPLIERS within the range selected by the user ......90 70: Conditions to filter the SUPPLIERS shown in the grid ................................................90 71:Data order in the grid ...........................................................................................91 72: Form of Working with SUPPLIERS with the possibility of positioning on a given line.....92 73: Work panel Visualize Supplier with fixed bitmap ....................................................93 74: Bitmap type variable definition ..............................................................................93 75: Load Event to load dynamic bitmap........................................................................94 76: Visualize supplier in runtime with dynamic bitmap....................................................94 77: Properties Dialog of work panel Working with SUPPLIERS.......................................95 78: Browser Call tree ..............................................................................................97
Page 110 of 111
NOTES:
Page 111 of 111

Gxap PDF

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Gxap PDF

Uploaded by

Copyright:

Available Formats

Designing Applications

Desinging Applications in GeneXus

2. Transaction object .......................................................................................................12

Form Editor ........................................................................................................................... 30

3. Report object ..............................................................................................................47

Conditions ............................................................................................................................. 68 Rules .................................................................................................................................... 69

Report Wizard ........................................................................................................................ 70 Properties.............................................................................................................................. 74

6. Work Panel object .......................................................................................................80

Integrity and redundancy controls............................................................................................. 79

7. Web object .................................................................................................................98 Appendix A. Relational Data Models ...................................................................................99

Desinging Applications in GeneXus

Desinging Applications in GeneXus

Defining the objective

Defining the work team

Obtaining a global idea

Defining the scope of the application

Keeping design simple

Being Data Oriented

Desinging Applications in GeneXus

Desinging Applications in GeneXus

Desinging Applications in GeneXus

GeneXus designs the database in third normal form.

Fig. 1: Tabs at the bottom of the transaction editing window

Desinging Applications in GeneXus

Fig. 2: Suppliers transaction structure

Based on this structure, GeneXus will build a table: SUPPLIERS

And it will create a default GUI form for the transaction:

Fig. 3: GUI Form of the Suppliers transaction

As well as a Web form:

Desinging Applications in GeneXus

Fig. 4: Web Form of the Suppliers transaction

Desinging Applications in GeneXus

Fig. 5: Define Attribute Dialog

Relationship between the structure and the data model

Other simple transactions of our application

Defining the Orders transaction

Subtotal 3000 6000 9000

Rules for attribute names

Transactions referential integrity

Ordered quantity Price ordered Order Line Amount

Header Level Lines Level

In GeneXus, the second level is represented as shown in the following figure:

Fig. 6: Orders transaction structure in GeneXus

Delivery date Amount to pay

Subtotal 3000 6000 9000

Desinging Applications in GeneXus

Types of relationships between the objects

An order has many items. An item may be in many orders.

Attributes to be accepted or displayed

Fig. 7: GUI Form - SUPPLIERS transaction

Desinging Applications in GeneXus

Field to field dialog

Full screen dialog

Input and output attributes

Fig. 8: Default GUI Form of the ORDERS transaction.

Selection Prompt Feature

Fig. 9: SUPPLIERS Selection List

Desinging Applications in GeneXus

Items transaction form

Attribute/variable controls type

Desinging Applications in GeneXus

Dynamic List Box