Rich Client and Online Differences (Magic xpa 3.x)

Online to Rich Client

Online programs are always converted to interactive Rich Client programs.

Calling Other Programs

In the Call operation's Destination property:

• In Rich Client, the property will search the destination in the Runtime tree.

• In Online, the property will only search subforms that are children of the current task.

In Online programming when a program calls another, the original program will be suspended, unless the programs are concurrent (what is referred to as “Parallel Execution”). However, when a Rich Client program calls another program, the calling program continues running concurrently with the called program, but under a single server context. If one chooses to call a program using the Parallel Execution setting, the calling program will open a new server context and will be considered the first program in a new runtime tree.

Closing a program calling a Parallel Execution program, will not close the called program.

To simulate the standard Online behavior, you should ensure that the called program’s form is Modal. This is performed by setting the program’s Window Type to Modal.

If the called program’s Window type was defined as Default, this is done automatically for you when migrating an existing program from C/S to RIA.

Operations

Unsupported Operations

The following operations are not supported for Rich Client tasks:

• Invoke COM

• Form (Output, Input)

Verify Operation

In Rich Client tasks, the Verify operation with the Append to Error Log property set to Yes, only works when the InternalLogFile setting is defined.

In Batch tasks called from Rich Client tasks, the Verify operation is executed on the client side after the Batch task is closed.

Unsupported Functions

Some of the regular Magic xpa functions are unavailable in a Rich Client task. Most of them have simple workarounds. Some functions are not supported in certain handlers. For example, KBPut() and KBGet() are not supported. Instead of these functions, you should implement them by using Raise Event operations and Event handlers.

The following functions are not supported:

Blob2Req File2Req CabinetUnload ClientCertificateAdd ClientCertificateDiscard DirDlg* FileDlg** KBGet KBPut MDate

PPD RQHTTPHeader RQHttpStatusCode SetContextFocus SNMPNotify Text TransMode UDF, UDFF, UDFS

VariantAttr VariantCreate VariantGet VariantGetVector VariantType WinHelp WSProvideAttachmentAdd WSProvideAttachmentGet XMLxxx

* Use the ClientDirDlg Function to open the Dir dialog box on the client side.

** Use the ClientFileOpenDlg and ClientFileSaveDlg functions to open the File dialog box on the client side.

Note: In Rich Client tasks, the User function only works if the Deployment Mode is set to Background.

Events

Internal Events

Some internal events are unavailable in a Rich Client task, such as the User Action 1 through User Action 20 events. Regular user events should be created and used instead of these events. Note that when changing a task to a Rich Client task, the User Action XX events will be converted to regular user events if such events are defined in the Main program.

Note that if such events are defined in the Model level, the Rich Client Preparation utility will convert them to the user events, so it is advisable to define the user events in the Main program before running the preparation utility.

The following events are not supported:

Close All Close Application Context Got Focus Context Lost Focus Mark Next Char

Mark Previous Char Next Word Next Window Open Application

Previous Window Previous Word Shell to OS User Action 1-20

The following events are supported only for Rich Client tasks:

• Browser Status Text Change

• Post Refresh by Parent

In the Control Modify event, for multi-selection controls:

• In Online tasks, the event is raised when leaving the control. The event will not perform recompute.

• In Rich Client tasks, the event is raised after each selection.

In the Screen Refresh event, if some records that exist on the screen were deleted from the database then:

• In Online tasks, these records will be removed from the screen.

• In Rich Client tasks, these records will not be removed from the screen.

User Events

For user events defined with Force Exit set to Pre Record Update or Post Record Update, the Control Verification logic unit will be executed:

• In Online tasks, only if the variable is changed.

• In Rich Clients tasks, always.

.NET Events

For .NET objects not placed on a form: In Online, the events will be raised in all contexts and in Rich Client only in the current context.

Calling Rich Client Task

When calling an Online task, only one task runs at a time. In Rich Client tasks, unless the called program is Modal, the caller and called programs keep running.

For a Rich Client called program, the CallProg function does not return the task return value. This is because the expression does not wait for the program to end. Parallel Rich Client programs called via this function will be opened as non-parallel programs.

Batch Tasks

A Batch task is not seen when called from a Rich Client tasks. This is because Batch tasks are executed on the Background engine on the Server side and, therefore, they cannot call interactive Rich Client tasks and will not show the form. If you need to execute a non-interactive task on the Client side, you can set the Rich Client task to be non-interactive.

When migrating an existing program from C/S to RIA, changing a Batch task to Rich Client automatically turns it into a non-interactive Rich Client task.

I/O

In Rich Client tasks, the I/O Device repository and I/O-related functions are not supported.

Reports

Reports can be displayed by printing the report into a PDF file and then displaying the PDF using its associated program. The PDF can either be transferred and saved on the client side, or accessed remotely by the client. An example of this can be found in the Developing Rich Client Applications concept paper. In this example, we used the Magic xpa Browser control to display the report.

Printing to a default printer or opening the Print Dialog or Print Preview will not work. This is because the printing is done in a Batch task that runs on the Background engine on the Server side and hence will not show the form.

Form

The following form properties are not fully supported:

• Window type – The Default window type is not supported in a Rich Client task.

• Show in Window Menu – Not supported. The Window menu itself is not supported.

You cannot specify the form on a Call operation.

Since version 2.1: A Modal window type halts the flow of all the other tasks so you cannot click another window without first closing this window:

• In Online tasks, Parallel tasks will also be halted.

• In Rich Client tasks, Parallel tasks will not be halted.

Phantom Tasks

Phantom tasks are no longer needed in Client-Server applications since the Subform control was introduced. Even so, the use of this feature is vast in existing applications. The Close Task Window property is inactive for Rich Client and cannot be set to No. Therefore, when leaving the Rich Client program, the window will always close. When migrating to RIA, if you want your program to stay open while working on another program, you must use a non-modal Rich Client screen or add a Subform control in the calling program with the phantom task/program as the called task program. Any excess code in the calling program has to be removed.

Control Properties

The following control properties are not fully supported in Rich Client tasks:

General

• Help – Only help screens of Type=URL are supported.

Radio Button control

• Multiline – Not supported.

• Radio buttons in a table – Radio buttons cannot be used in a Rich Client table.

Table control

• Multi Marking – Not supported.

• Bottom Position Interval – Not supported.

Column control

• Top Border – Not supported.

• Right Border – Not supported.

Tree control

• Multi Marking – Not supported.

• Keep tree view – Behaves as Yes.

Behavior of Controls

Some controls behave differently in the Rich Client and the Online environment. You should be aware of the following differences so that you can take them into account when programming:

• Browser control – The Browser control is only supported in Rich Client tasks.

• Edit control – The Rich Client and Online behavior differs when writing an illegal value in an Edit control (for example ‘3.3’ in a numeric field with a picture of ‘2’). In Online programs, the inputted value reverts back to the previous input value. In Rich Client programs, the value remains the same, so the user needs to fix it before moving to another control.

• Push Button control – When clicking on a push button with no variable that raises the Zoom event:

o In Online tasks, the Zoom event is raised only if parking on a control that has a Zoom handler for itself.

o In Rich Client tasks, the Zoom event is raised.

• RTF Edit control – The Rich Client and Online behavior differs when you want to attach a color, font, or paragraph setting to the RTF Edit control:

o In Rich Client programs, attach a variable with a Binary Blob attribute to the Rich Edit control.

o In Online programs, attach a variable with a Unicode Blob attribute to the Rich Edit control.

If you use any other attribute than described above, the color, font or paragraph setting may be removed when updating the content of the Blob.

• Cursor position after clicking on a non-parkable control:

o In Online tasks, the cursor is repositioned on the nearest parkable control.

o In Rich Client tasks, the cursor remains at the current location.

• Table control –

o Changing the value of a Virtual variable that is displayed in a table will result in the refreshing of the Virtual variable’s appearance in all of the rows.

o Using the scrollbar to browse the table will not move the current record.

• Subform control – In an Online environment, if a task is displayed with a subform, the task is naturally closed when the cursor leaves the task. In the Rich Client environment, the task will continue executing until the container task is closed. Here are issues that you need to be aware of:

o The subform's Task Prefix and Task Suffix logic units are executed only once.

o The IsFirstRecordCycle function will be executed only once.

o When you use the same data source in various subforms, using the Data Source Name property will affect all of the subforms using that data source.

o Raising an Exit event within a subform task (via the Esc button, for example) will raise the event in the Subform container task and as a result exit both programs. If you do not want to exit the parent program, the Exit event can be caught. If there is a double exit, it should be canceled in order to exit the parent program.

o It is possible to define that pressing the Tab key from the subform will move to the next control of the parent. Refer to Tabbing cycle.

o Clicking on the subform area in Rich Client will keep the cursor at the current control and not move the focus to the subform task.

o When the Refresh When Hidden property has an expression, the behavior will be according to the expression value at Runtime. If the expression value becomes True:

1. 1. • In Online tasks, the subform will be refreshed immediately.

      • In Rich Client tasks, the subform will not be refreshed immediately.

o When evaluating an operation in the Task Prefix or Record Prefix logic units that suspends the form load, such as a Verify operation, then:

1. 1. • In Rich Client non-Offline tasks, the subform will be drawn before that operation.

      • In Online and Rich Client Offline tasks, the subform will be drawn after that operation.

Variables

Variables of type OLE are not supported. These need to be transferred to a batch program that will run on the server side.

Status Bar

The status bar in Rich Client applications contains only the messages section, so you can only receive error messages and prompt helps. It does not include, for instance, Zoom, INS and OVR.

This means that if a control has a Zoom handler defined on it, there will be no indication of this functionality in the status bar. You will need to implement this functionality yourself by adding a prompt help for the control or model.

You can use the SpecialShowStatusBarPanes setting to show the task mode in the status bar. Since version: 2.2

Physical Transactions

Physical transactions are not supported.

For Rich Client programs that require data modification (create, update, delete), a deferred transaction is required. If a deferred transaction is not set, only data reading will be available.

If the application depended on a physical lock to the database as a means of serializing access to programs, the programmer must find alternative solutions to this. One possible alternative is to make use of the Lock() and Unlock() functions.

Parallel Contexts

The Initiate Main Program task property is not supported in Rich Client tasks.

Event raising between parallel contexts is not supported. The use of parallel programs can be reduced since several tasks can run simultaneously in Rich Client tasks. Wherever applicable, one can disable the “Parallel execution” of the programs involved. Note the differences between calling a parallel and a non-parallel program in the Calling Other Programs section above.

Environment Settings

The Center Screen in Online environment setting is not supported.

Client-Side and Server-Side Expressions

Client-side expressions cannot be used in the init property of a Rich Client task.

Mixed expressions cannot be used.

Mixed operations with expressions that will be executed on another side cannot be used.

Control and form properties cannot use server-side expressions.

Related Topics

Offline and Non-Offline Differences