Upon executing the Save, Check, Load or Delete methods, the messages automatically generated by GeneXus (those issued by GeneXus through data consistency controls, uniqueness of primary key values, etc.) are triggered as well as our own Error and Msg rules defined in the transaction.
Even when these controls are automatically triggered, for the end user to be aware of this, we must obtain and explicitly show the messages issued.
Now, how do we recover the messages occurred?
We use the structured data type Messages that GeneXus defines automatically upon creating a new KB:
This collection data type is meant to allow access to the messages issued in the execution of a Business Component.
So, in the object we are using the Business Component concept we define two variables:
- &Messages: of the Messages data type, collection
- &oneMessage: of the Messages.Message data type, which is 1 element in the collection
Let's suppose we define the Customer transaction as Business Component (by setting its Business Component property = True):
CustomerId* (Autonumber property = True) CountryId* (Autonumber property = True)
error('The customer must be 18 years old or more') if CustomerBirthDate.Age()<18;
Accordingly, a business component data type of the Customer transaction is automatically created in the KB and we are able to define in any object a variable of the new type created. Thus, in any object we define a variable named &customer based on the Customer type and:
- - we codify what we need to do with the &customer variable
- - we apply the save method to the &customer variable
- - we want to handle the errors may have ocurred, so, the following code shows how we can obtain the errors that happened in a collection variable and iterate the collection for advising the user (or doing something else):
&Messages = &customer.GetMessages() //we obtain the messages that may have ocurred (we extract and load them in the &Messages collection)
for &oneMessage in &Messages //we iterate the collection
Case &oneMessage.Id ='PrimaryKeyNotFound'
msg('The customer does not exist')
Case &oneMessage.Id ='ForeignKeyNotFound'
msg('The country does not exist')
Case &oneMessage.Id= 'RecordWasChanged'
msg('The customer record was changed by another user')
Case &oneMessage.Id ='DuplicatePrimaryKey'
msg('A customer with equal identifier already exists')
Most common messages defined by GeneXus:
||Data with the specified key could not be found
||Record already exist
||No matching 'TableName'
||You can't update a record without reading it first
||Invalid delete, related information in 'TableName'
||Record is in use by another
||'AttributeName' is out of range
||'TableName' was changed
- OutOfRange: Applies to an attribute wich has set the Value Range property or an attribute based on an Enumerated Data type.
- If there are any object name conflicts with the SDT "Messages", when a knowledge base is converted to 9.0 version, the object will be rename see compatibility section ...
Error and Msg rules defined by the user in the transaction rules:
The Error and Msg rules allow you to include messages in the messages collection (SDT). When you define Error and Msg rules you can set the Id optional parameter, following this syntax:
Msg('Message phase', Id);
Error('Error phrase', Id);
i.e.: Error("Customer name cannot be empty", CustomerNameCannotBeEmpty) if CustomerName.isempty();
The CustomerNameCannotBeEmpty parameter is considered as the "Id" property of the messages SDT.
- For the GeneXus standard messages, the "Id" is ever in English, no matter the model configured language.
- For your own "Id", however they can be just a code like "1", "2", "3" or "Error1", "Error2", we recommended to define explanatory texts id like "CustomerNameCannotBeEmpty". The reason is that the code will be clearer. For example: "If &Customer.GetMessages().Item(1).Id=CustomerNameCannotBeEmpty is clearer than "If &Customer.GetMessages().Item(1).Id=1"
The "Type" is based on a enumerated domain. You can ask about this values: MessageTypes.Warning and MessageTypes.Error.