Online documentation - Websydian v6.5 |
Introduction Implementing Parts
This page explains how to implement the MessageStore pattern and how to add additional application messages to an application.
Implementing the Message Store pattern enables the use of a Websydian Message Store for reporting system error messages thus making it possible to report system messages in multiple languages. Implementing the Message Store pattern will also provide the basis for defining and using new application-specific messages in the Websydian application.
First, a Message Store entity object must be instantiated by inheritance from the MessageStore library pattern in the WSYPRES library:
MyMessageStore | is a ENT | MessageStore |
The local MyMessageStore entity will now scope the data entities, abstracts and services needed to implement full Message Control by the application.
All Message Store Data entities must inherit from RelationalTable:
MyMessageStore.Data.Message | is a ENT | RelationalTable EditDetail |
MyMessageStore.Data.MessageParameter | is a ENT | RelationalTable EditDetail |
MyMessageStore.Data.MessageType | is a ENT | RelationalTable EditDetail |
MyMessageStore.Data.Template |
is a ENT |
RelationalTable EditDetail |
The inheritance from EditDetail (or from EditDialog) FOUNDATION pattern is necessary in order to have language triples defined for the server functions.
The Message Store Template entity relates to an abstract Language entity known by a LanguageCode field. If the Message Store pattern is used for implementing multi-language messages, the abstract Language entity as well as the LanguageCode field must be replaced.
MyMessageStore | replaces ENT ...by ENT |
MyMessageStore.Abstract.Language MyLanguage |
replaces FLD ...by FLD |
LanguageCode MyLanguageCode |
It is assumed that the MyLanguage entity contains all the languages used by the application.
If the Message Store pattern is used only for implementing single-language messages, the replacement can be omitted and the Data.Template entity should then not be implemented at all.
The Data.Message entity must have a unique number assigned to its MessageSeq key field. This may be done by defining a MySurrogateSystem entity based on the SurrogateSystem pattern, and then by adding the following triples:
MyMessageStore.Data.Message | is a ENT | Surrogate |
replaces ENT ...by ENT |
SurrogateSystem MySurrogateSystem |
|
replaces FLD ...by FLD |
Surrogate MessageSeq |
The result of these declarations will be an incremented sequence number automatically being assigned to the MessageSeq field of new Message-records.
In order to activate the Message Store functionality, all Page Generator and Event Handler functions in the Websydian application must inherit from the abstract ActivateMessageStore function. Typically, all Event Handlers and Page Generators in an application will inherit from a common abstract template function. By applying the inheritance triple to these template functions, all Page Generators and Event Handlers in the Websydian application will inherit from ActivateMessageStore:
MyTemplatePageGenerator | is a FNC | Abstract.ActivateMessageStore |
MyTemplateEventHandler | is a FNC | Abstract.ActivateMessageStore |
In the same way, the Dispatcher function of the Websydian application must inherit from the Abstract.EventDispatcher pattern of the implemented Message Store:
MyDispatcher | is a FNC | Abstract.EventDispatcher |
These inheritance definitions will result in system errors to be saved and reported by the Message Store pattern by all Websydian main functions in the application. The inheritance triples will further provide a subroutine to be called for displaying application-specific messages (see below).
If the Message Store pattern is used to implement multi-lingual messaging, the Language Code field in the MessageStoreFields variable must be set by the Dispatcher function.
The best way to implement this functionality is to add the key field of the implemented Language entity to the implemented Session entity. The current Session is always read by the Dispatcher function, and in this way the MessageStoreFields<LanguageCode> field can be assigned from the corresponding Session field returned from the ValidateAndUpdateSession function (should be done in the After session update edit point).
Using the Session functionality also requires that the Language Code field is specified when the Session is created by the CallFirstPageGenerator function scoped under the Dispatcher function. This can be done by defining the Language Code field as input to the Session.Update.CreateSession function and specifying the Language Code as a local field in the Dispatcher.CallFirstPageGenerator function. A value must be assigned to the local Language Code field in the 0 Before calling session creation edit point as well as the field must be used for parameter mapping in the inherited call to the Update.CreateSession function. Further, the Output<LanguageCode> of the CallFirstPageGenerator function must be set to the selected Language Code.
The Message Store pattern links the standard Websydian error messages with the error messages defined in the Message Store by using the implementation name of the standard error message object.
As the message objects defined by the Session pattern are scoped to the EventDispatcher function they do not have an implementation name as the objects are inherited.
For the Message Store to work properly the message objects scoped to the EventDispatcher should have the implementation names listed in the table below.
It is necessary to follow the instructions below to implement Session Messages.
Since Plex does not allow an implementation name to be created twice the implementation names must be created using the following procedure:
Message Object | Implementation Name |
---|---|
MyEventDispatcher.CallFirstPageGenerator.Error creating session | WSY1001 |
MyEventDispatcher.Session does not exist | WSY1002 |
MyEventDispatcher.Session has different IP address | WSY1003 |
MyEventDispatcher.Session Key not present | WSY1008 |
MyEventDispatcher.Session not active | WSY1004 |
MyEventDispatcher.Session timed out | WSY1005 |
Before generating and building any Message Store objects, all objects scoped under the defined Message Stores entity (MyMessageStore) must be made real, and the group model must be updated. In this way, non-negative internal surrogate numbers are specified for all new Message Store objects.
Generate and build all objects scoped under the Data entity and the functions scoped under the Services and MessageFunctions objects under the defined Message Store pattern.
Re-generate and build the Dispatcher function and all Page Generators and Event Handler functions for which Message Store functionality has been applied.
Ignore warnings on Dump and Load functions, if the Template entity is not implemented (i.e. the Message Store is not implementing multi-language messaging).
From the Generate and Build window, run the Services.EditMessageTypes function.
No Message Type records have been created in the database yet. This is done by pressing the Model Update push button which will result in a call to the scoped UpdateMessageTypes function.
Refresh the Message Type list to see the created Message Type records.
The Group Model must be updated and the UpdateMessageTypes function must be re-generated, built, and run, each time new Message Type functions are added to the model or existing Message Types are changed.
Translation of the application messages is necessary if using the Message Store pattern to implement multi-language messaging.
Message texts (system messages as well as application messages) are translated by extracting/exporting the message texts to a file, translating the file, and then importing the translated files back into the Message Store database.
The procedure described below must be repeated for each language to be supported by the Message Store.
From the Edit Message Types Windows panel, select the File Transfer buttom. Now, specify a Language Code and the name of the Template file to be generated and select Dump:
Specify parameters for Message translation in the Template Message Translation window.
The exported Message translation file will be stored in the folder where the Windows programs are executed from.
If the application group model has not been updated, selecting Dump will result in an error message.
Open the generated translation file with Notepad or another text editor:
Translation file generated from the Message Types default texts.
The generate translation file can now be translated and saved.
When the message file has been translated, the translated messages types can be re-imported into the Message Store database by selecting Load from the Template Message Translation panel.
By default, the Message Store pattern will implement the existing Websydian and CA Plex system and application error messages. But, the Message Store pattern as well can be used by the developer to define and use application messages.
This section specifies how to add a new Application Message to the implemented Message Store.
Specify a new function scoped under the MessageFunctions function, and have the new function inherit from Abstract.CreateMessage:
MessageFunctions | includes FNC | MyMessageType |
MyMessageType | is a FNC | Abstract.CreateMessage |
option NME ...value SYS |
Application Error Yes |
The option-triple specifies the type of Create Message function which will typically be Application Error. Other types of messages are System Error, Alarm, Warning, Informative, and Other.
New Create Message functions may be specified in two levels under the MessageFunctions function.
Some messages need parameters as input so that the message displayed will be context-sensitive.
Specify such parameters as field input to the Create Message function for the MessageParameters variable, e.g.:
MyMessageType | input FLD | FieldA FieldB |
Next, specify the message text as the large property of the DefaultTemplateText message object scoped by the new Create Message function.
Specify the default message text in the large property of DefaultTemplateText message object scoped under the Create Message function.
Use a &-sign to specify message parameters.
If using Export and Import of translation files for message translation (see below), the message text must not include line-shifts. If line-shifts are necessary, they must be inserted in the DefaultTemplateText field of the Template record through a Windows application panel.
Typically, application messages are displayed by Event Handler functions (called from the 0 Process of input edit point) during validation of input data. This is done by specifying a call to the Create Message function followed by a call to the Get and report message subroutine.
Example:
The MyMessageType application message is created and displayed by adding the following two action diagram statements:
Call MyMessageStore.MessageFunctions.MyMessageType
Go sub Get and report message
When specifying the call to the MyMessageType Create Message function, map with the MessageStoreFields<MessageSeq> field.
When specifying new Message Store objects, the group model must be updated. In this way, non-negative internal surrogate numbers are specified for all the new Message Store objects.
Generate and build the following functions:
Run the Edit Message Types Windows function and press the Model Update button. If the Update Chg. checkbox is checked, any changes to the existing Message texts in the CA Plex model will also be updated in the Message Store database.
Finally, run the Export/Translate/Import translation file process again (see former section above).