Implementing the MessageStore Pattern

Introduction    Implementing     Parts

• Implement the Message Store Pattern
  • Inherit from MessageStore Pattern
  • Inherit from RelationalTable
  • Replace Language Specifications
  • Apply Surrogate Functionality to Message Entity
  • Inherit from ActivateMessageStore and EventDispatcher Patterns
  • Assign Value to Language Code in Dispatcher Function
  • Apply Implementation Names to Session Messages
  • Make Objects Real and Update Application Group Model
  • Generate and Build Message Store Objects
  • Re-Generate and Build all Websydian Main Functions
  • Create Message Type Records
  • Export, Translate, and Import Message Files
• Define and Use Additional Application Messages
  • Define Create Message Function
  • Specify Parameters and Text for Message
  • Call Message Function from Application Code
  • Update Application Group Model
  • Generate and Build Functions
  • Create New Message Type in Message Store Database

This page explains how to implement the MessageStore pattern and how to add additional application messages to an application.

Implement the Message Store Pattern

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.

Inherit from MessageStore Pattern

First, a Message Store entity object must be instantiated by inheritance from the MessageStore library pattern in the WSYPRES library:

The local MyMessageStore entity will now scope the data entities, abstracts and services needed to implement full Message Control by the application.

Inherit from RelationalTable

All Message Store Data entities must inherit from RelationalTable:

The inheritance from EditDetail (or from  EditDialog)  FOUNDATION pattern is necessary in order to have language triples defined for the server functions.

Replace Language Specifications

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.

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.

Apply Surrogate Functionality to Message Entity

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:

The result of these declarations will be an incremented sequence number automatically being assigned to the MessageSeq field of new Message-records.

Inherit from ActivateMessageStore and EventDispatcher Patterns

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:

In the same way, the Dispatcher function of the Websydian application must inherit from the Abstract.EventDispatcher pattern of the implemented Message Store:

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

Assign Value to Language Code in Dispatcher Function

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.

Apply Implementation Names to Session Messages

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.

Since Plex does not allow an implementation name to be created twice the implementation names must be created using the following procedure:

1. Create an implementation name that does not exist for the message object, e.g. _WSY1001.
2. Rename the name object _WSY1001 to WSY1001-
3. Apply the previous steps to all the scoped message objects.

Make Objects Real and Update Application Group Model

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 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 all Websydian Main Functions

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

Create Message Type Records

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.

Export, Translate, and Import Message Files

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.

Export Message File

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.

Translate Message File

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.

Import Translated Message File

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.

Define and Use Additional Application Messages

By default, the Message Store pattern will implement the existing Websydian and AllFusion 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.

Define Create Message Function

Specify a new function scoped under the MessageFunctions function, and have the new function inherit from Abstract.CreateMessage:

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.

Specify Parameters and Text for Message

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

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.

Call Message Function from Application Code

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.

Update Application Group Model

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 Functions

Generate and build the following functions:

• The new Create Message function
• Any functions (typically Event Handlers) calling the new Create Message function
• EditMessageTypes.UpdateMessageTypes
• EditMessageTypes.TemplateMessageTranslation.DumpMessageTemplates

Create and Translate New Message Type in Message Store Database

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