How Do I Work with the Magic xpa Engine as an Event-Driven Engine? (Magic xpa 4.x)

Back in the COBOL days, programs were mainly procedural. That is, the program started at the top, and kept going until it got to the bottom. There was little or no input from the user, other than to start the program.

Today though, most programs are event-driven. That is, the program sits there and waits for something to happen. When something happens, it responds in a specific away.

Some simple examples of this are websites and SOAP services. The website is always there, but only responds when you press a key, or hover over a certain field. SOAP services return strings of data, but only if you send them certain strings of data.

You can write both kinds of programs in Magic xpa, but mostly you will be using the event-driven paradigm even in batch programs. This is basically because it is a paradigm that is easier and more efficient to use than the old procedural methods.

The Concept of Events

The basic concept of events is simple. Something happens (the trigger) and the program responds by executing some logic (the handler).

The trigger is often something the user does, such as hovering over a certain field or pressing a certain key. Or that the cursor moved into a field, or it moved out of a field. It can also be something that does not happen; for example, the keyboard is idle for too long. Or a certain time was reached.

However, programs also raise events specifically to interact with other programs.

Here are some of the things that can happen:

What happens	How it is handled in Magic xpa
Events	Logic Header	Subtype
A task just started	Task	Prefix
A task just ended	Task	Suffix
A new record was just read	Record	Prefix
The user just moved off this record	Record	Suffix
The user moved the cursor into a field	Control	Prefix
The user moved the cursor out of a field	Control	Suffix
No one touched the keyboard for x seconds	Event	Timer event
The user pressed a push button	Event	User event
The value of a certain variable just changed	Variable Change
It just turned 11:03 AM.	Event	Expression
The user pressed a certain key or key combination	Event	System
There was a DBMS “Duplicate Record” error.	Event	Error

Although there are hundreds of possible events you can handle, in reality most of the routine work is done automatically for you by Magic xpa. For instance, you do not have to explicitly open or close DB tables, and initialization, default values, and most of your data validation can be handled by your field models. You can also attach selection lists at the model level, or as part of the control on the form, either as called selection list programs or as dynamic combo boxes.

For the events you do want to handle, you will add some lines to the Logic section of your task. Let’s take a simple example, forcing entry of a required field.

Prerequisite: The control must already be on the form, and have a control name.

Creating a logic unit

1. In your task, click on the Logic tab (Ctrl+1).

2. Move to the line where you want to enter your logic unit.

3. Press Ctrl+H (Edit->Create Header Line) to create a new logic header.

4. Select the logic unit type Control. Tab to the next field.

5. Select the control type of Verification. Tab to the next field.

6. Zoom (F5 or double-click) on the of: field to select the control you want to verify. If you don’t see your control on the list, either it is not on the form or it does not have a control name.

You now have a logic unit that will execute whenever the user passes the field in question. Inside that logic unit, we added a Verify operation, which will in this case give an error message in a box and prevent the user from doing anything else until they enter some data in the field.

See also

The Event Handling concept paper

How Do I Utilize the Event Hierarchy?

The Online and Rich Client Samples projects (program EN01 and REN01)