Error handling in Business Components

Official Content
This documentation is valid for:

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: 

MessagesSDTImage 

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

VariablesBasedOnMessagesSDTImage

Example

Let's suppose we define the Customer transaction as Business Component (by setting its Business Component property = True):

Customer                                                                Country  
{                                                                       {     
  CustomerId*     (Autonumber property = True)                             CountryId*     (Autonumber property = True)
  CustomerName                                                             CountryName 
  CustomerAddress                                                       }
  CustomerPhone
  CustomerEmail
  CustomerBirthDate
  CustomerAddedDate
  CountryId
  CountryName   
}

Customer rules:

Default(CustomerAddedDate,&today);
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:

  1. - we codify what we need to do with the &customer variable
  2. - we apply the save method to the &customer variable
  3. - 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):
....
&customer.save()
If &customer.Fail() 
   &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 
      Do case
      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')
      Otherwise
           msg(&oneMessage.Description) 
      Endcase       
   endfor
endif


Most common messages defined by GeneXus:

Id Type Description
PrimaryKeyNotFound MessageTypes.Error   Data with the specified key could not be found
DuplicatePrimaryKey MessageTypes.Error Record already exist
ForeignKeyNotFound MessageTypes.Error No matching 'TableName'
CandidateKeyNotFound MessageTypes.Error You can't update a record without reading it first
CannotDeleteReferencedRecord MessageTypes.Error Invalid delete, related information in 'TableName'
RecordIsLocked MessageTypes.Error Record is in use by another
OutOfRange MessageTypes.Error 'AttributeName' is out of range
RecordWasChanged MessageTypes.Error   'TableName' was changed

 

Notes:
 - 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.

 

Considerations

Id
   -  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"

Type

The "Type" is based on a enumerated domain. You can ask about this values: MessageTypes.Warning and MessageTypes.Error.