Thin Client Deployment TM of Clarion Programs

Version 6.3001 25-JUNE 2007

COPYRIGHT 2007-2008 Ivan Grech Mintoff. This publication is protected by copyright and all rights are reserved by Ivan Grech Mintoff. It may not, in whole or part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form without prior consent, in writing, from Ivan Grech Mintoff. This publication supports ClarioNET 6.3. It is possible that it may contain technical or typographical errors. The author provides this publication as is, without warranty of any kind, either expressed or implied. ClarioNET Solutions 132 Triq Fleur-de-Lys, Birkirkara, Malta, EU. www.clarionet.com

Trademark Acknowledgments: ClarioNET is a trademark of Ivan Grech Mintoff. Clarion is a trademark of SoftVelocity Inc. SoftVelocity is a trademark of SoftVelocity Incorporated. Microsoft and Windows are registered trademarks of Microsoft Corporation.

The ClarioNET installation is produced using SetupBuilder by Lindersoft ( http://www.lindersoft.com ) which we recommend highly to anyone who may need to create an installer for software!

All other products and company names are trademarks of their respective owners. Version 6.301

CONTENTS

CONTENTS
Introduction Documentation What to Read First Manual Conventions Clarion Application Broker Technical Support Product Overview What is ClarioNET ? Thin Client Computing Clarion in the Thin-Client World Architecture Server Program How It Works Setup Running the Setup Program BUILTINS.CLW Non-ABC Template Modifications Required Template Registry Setup Licensed vs. Trial Status Files Installed Applying ClarioNET To Your Application Applying the ClarioNET Template Important ! ClarioNET in Hand Coded Applications Template Options Enable ClarioNET Product Activation Code ( PAC ) Application Visible on Server Windows HELP Sent to Client INI Files Default to Client Reports Use a Progress Bar Implement as Continuous Connection Client Refresh Interval (minutes) 13 13 14 14 14 14 15 15 15 15 16 16 7 7 8 8 9 10 3 3 4 4 5 5 1 1 1 2 2

CONTENTS CONTENTS
Client Auto Shut Down Server Auto Shut Down Use ABC Toolbar CPCS Report Generation Compatibility Server LoadStar RPM Templates Compatibility Program Design Considerations Introduction Design Guidelines Defines Window Management INI File Management Help Files Graphics Statements Security Encryption User Access Server Access User Interface Considerations Application Design Reviewing Source Code Procedures Controls That Do Not Appear Running via ClarioNET Reports in ClarioNET Server Printing Setup Considerations ClarioNET Server Side Report Programming Performance Tip..... Client Side Report Processing Disabling Client Side Empty Report Message Overview of Report Processing Procedures How to Transfer Files Server to Client File Transfers using HTTP Server to Client File Transfers using FTP Client to Server File Transfers using HTTP Client to Server File Transfers using FTP How to Use Command Line Parameters Startup server information sent to client Calling Procedures in the Client 33 34 36 38 41 42 43 27 28 28 28 29 29 19 19 21 21 22 23 23 23 23 23 24 24 24 25 26 16 16 17 17 17

CONTENTS ClarioNET:ClientProcedure Placing a HyperLink in the Server Program How to Change a Client Side Cursor How to Display a Splash Screen at Startup Server Side Class Information Server Class Defined Initialization and Closedown Client Queries : A Hidden Jewel PushWindow : Forced Client Window Display PushWindow Example.... Window Management ClarioNET:OpenWindowInit ClarioNET:InitWindow ClarioNET:OpenWindow ClarioNET:TakeEvent ClarioNET:CloseWindow ClarioNET:KillWindow ClarioNET:RegisterBrowse Miscellaneous Procedures ClarioNET:ClientBeep ClarioNET:SetUpdateExtents ClarioNET:GetTempDir ClarioNET:GetClientIPAddress ClarioNET:AbortCloseWindow ClarioNET:GetINI ClarioNET:PutINI ClarioNET:INIMode ClarioNET:SetWindowPos ClarioNET:ClientEventControl RunCallClass Client Application Class Class Properties ClarioNET Client Startup Procedures ClarioNET:StartServerProgram ClarioNET:StartClientSession How ClarioNET Manages Window Properties When building a client window 66 57 57 57 57 57 57 58 58 58 59 60 61 65 65 65 55 55 55 55 56 56 56 43 45 46 47 48 48 49 51 53 54

CONTENTS
WINDOW Complexity Limitations WINDOW Properties Supported Controls Property Support BOX BUTTON CHECK COMBO ELLIPSE ENTRY GROUP IMAGE ITEM LINE LIST MENU OPTION PANEL PROMPT PROGRESS RADIO REGION SHEET SPIN STRING TAB TEXT General Property and Control Notes Optimizing Scanning for Control Changes ClarioNET:SetUpdateExtents CREATEing and DESTROYing Controls at Runtime The REQ Attribute : Required Fields MOUSEX() and MOUSEY() Redirected STD: function calls STD:Close STD:Help, STD:HelpIndex, STD:HelponHelp, STD:HelpSearch STD:PrintSetup 88 88 88 86 86 87 87 87 67 68 70 70 70 71 72 74 74 76 76 77 77 78 78 78 79 79 80 80 81 82 83 84 84 84

CONTENTS

Redirected Clarion Standard Procedures Redirected Standard Dialog Boxes Run-Time Property Handling PROP:AlwaysDrop PROP:DeferMove & PROP:LazyDisplay SYSTEM{PROP:ColorDialogHook} SYSTEM{PROP:FontDialogHook} SYSTEM{PROP:PrinterDialogHook} SYSTEM{PROP:FileDialogHook} PROP:HaltHook, PROP:StopHook, &PROP:AssertHook PROP:MaxHeight, PROP:MaxWidth PROP:MinHeight, PROP:MinWidth PROP:NoTips PROP:AcceptAll & SELECT() PROP:Checked PROP:ChoiceFEQ PROP:Edit PROP:EventsWaiting PROP:Follows PROP:HscrollPos &PROP:VscrollPos PROP:IconList PROP:PrintMode PROP:LineHeight PROP:Threading PROP:Touched PROP:LineHeight Forced Shutdown User stops using client program but does not exit Communication between client and server has been severed Notes for Hand Coders ClarioNET Window Procedure Call Locations Problems and Limitations Client does not launch program Client launches program but during usage it freezes Problems in custom or third party code ClarioNET Server Side Procedures Calls MUST be in specific locations Calling Procedures That Display Windows in EVENT:Timer

89 90 91 91

91 91 91 91 91 91 92 92 92 92 92 92 93 93 93 93 93 93 93 93 94 95 96 98 98 98 99 99

CONTENTS
Window Size is Incorrect on Client A Call to POPUP Can Hang the Server Window Controls on the Client are in the Wrong Order or MISSING Report Progress Windows that Require an EVENT to start printing Windows with PROGRESS Controls Printout Size Limites or Orientation Missing ICON or IMAGE contents Do Not use EVENT:Last in the Server program Data within LIST is not formatted correctly or columns are shifted Wrong BUTTON has Default Behavior Calling other Window procedures during Window startup Program "Lockup" Font Sizes on the Client MDI Apps become SDI Apps LIST Has Scrambled Entries API Calls That Write to Server Screen Third Party Code or DLL's Additional Programming Guidelines Error Messages 99 100 100 100 100 100 101 101 101 101 101 101 102 102 102 102 102 103 104

Introduction
iDocumentation
What to Read First Everything you need to know to apply ClarioNET to a Clarion Application should be in this book. If one of your questions is not answered we want to know! Please email ivanmintoff@clarionet.com and tell us how we can make this document even more useful for you. To enjoy the fastest way to get acquainted with ClarioNET we suggest that you: Skim the Product Overview section in this chapter and be sure you read the white papers located at www.clarionet.com. Run the Setup program for ClarioNET to install the development system on your computer. The README.TXT file is also the only location where you can review the most up-to-date information not included in the manual. Have the Clarion Application Broker installed on the computer youre using to develop your ClarioNET application, even if you intend to deploy on another machine (see chapter 10 for additional information). After those initial steps we sincerely hope that you read through this entire document. Weve designed it as a reference and a users guide to assist you in answering the How Do I...? and What parameter does this function take? questions.

Manual Conventions Symbols are used in the syntax diagrams as follows: Symbol [] () Meaning Brackets enclose an optional (not required) attribute or parameter Parenthesis enclose a parameter list.

|| Vertical lines enclose parameter lists, where one, but only one, of the parameters is allowed. Coding example conventions used throughout this manual: IF NOT SomeDate SomeDate = TODAY() END

Introduction
IF and NOT are keywords ! SomeDate is a data name _6?,); =?@ -?, =HA ?AOM?H@I Any word in ALL CAPS is a Clarion language keyword. DataNames use mixed case with caps for readability. comments are predominantly in lower case. The purpose of these conventions is to make the code examples readable and clear.

Clarion Application Broker

ClarioNET requires the SoftVelocity Clarion Application Broker (an EXE file) to interface the Clarion program to the TCP/IP transport capabilities of Windows. This program is named C60APS50.EXE in the Clarion 6.0 distribution. Please consult your License Agreement to verify your ability to redistribute this file to your users. The ISAPI Application Server offered with previous versions of Clarion has not proven to work well at the level of knowledge most users possess. The ClarioNET Server Deployment Manager is designed to use the Application Broker.

Technical Support
You can receive technical support for ClarioNET on the Internet. .Access the comp.lang.clarion newsgroup through any USENET server. Access the SoftVelocity.products.ClarioNET newsgroup which is hosted only on the news.softvelocity.com news server. Visit ClarioNETs Web page at http://www.clarionet.com for further ClarioNET resources.

2 -Product Overview

2 -Product Overview
What is ClarioNET ?
ClarioNET extends a Clarion program to provide a remote user interface. The remote interface and actual program are launched and stay connected over a TCP/IP connection that uses Internet style server operation. ClarioNET operates by adding calls to a Clarion PROCEDURE so that ClarioNET can monitor the startup, ACCEPT loop cycling, and shutdown of a Clarion program and all of it's procedures. What the user experiences is an actual duplicate of the running Clarion program....NOT a HTML approximation. If you have used Microsoft Terminal Server, Remote Desktop, or Citrix Terminal Server you can appreciate that ClarioNET give the same direct duplication of your program. ClarioNET is a very carefully written program that uses highly optimized screen scanning, data compression, and encryption techniques to give extremely robust performance. The ultra-small dataflow between the host and client computers results in great performance even on dial-up type connections. ClarioNET is the only "Thin Client" solution for Clarion programmers (other products use non-native user interfaces (using a mixture of HTML, Java, XML, etc.). The "thin client" designs means that ClarioNET is designed for a minimal footprint on the client computer. The program used by the remote "client" computer is a single EXE file (usually less than 500k). It does not require Internet Explorer or other large host programs. The ClarioNET client is quickly downloaded and launched.....the user experiences an actual Windows program appear and can work with it not even perceiving it is a remotely executing program.

Thin Client Computing

Thin Client computing has become the vision of the future for distributing application software to users desktops. Thin Client refers to a small, self-contained program that resides on the users (client) computer that displays screens and processes only keyboard and screen input. It is directly linked to the real program that is running at a remote location....on a powerful server. The two programs operate by exchanging information. The client tells the server what mouse and keyboard actions the user has performed. The server tells the client what to display to the user. This type of software design has many advantages over the early method of software distribution and usage: The software and data are installed just once on a centralized server. There are no large installation tasks on the client systemjust a simple single file executable program.

2 -Product Overview

The database is held on a high speed, secure file server with a quality backup plan in place. When updates are released there is no distribution; only the server files need to be changed. The program is available from many locations available to the user. No need to manage multiple installations and mirrored databases. Access to the software can be easily controlled, both at startup and at the lowest procedure access level. In any company, configuration and management strategies for departmental usage are trivialized and client hardware requirements are vastly simplified. There are many, many more advantages that come to light when a specific business model or need is analyzed. Uses from application hosting/rental, WAN program distribution, and support for field personnel are all within the realm of what ClarioNET offers.

Clarion in the Thin-Client World

ClarioNETTM provides thin-client and n-tier solutions for ClarionTM development. With Clarion for Windows and the ClarioNET extension library, programmers can create a single code base that can produce both native Windows applications and Intranet/Internet applications. Clarion developers can now offer TWO options for deployment: The application can run as the normal Microsoft Windows executable from their desktop. The user can run the Client side User Interface only. The application itself executes on an Intranet or Internet server connected to the User Interface over the HTTP (web) protocol. The user experiences the same rich Windows interface with speedy performance and full functionality....with zero additional programming or capability loss.

Architecture
For a ClarioNET deployment you actually create two different executables programs:

2 -Product Overview

Server Program
The actual Clarion application which is the program that contains the functionality. These are the EXE and DLL files that can run as a standalone desktop application -or-can reside and run on a server running either Microsoft Internet Information Server or the Clarion Application Broker. This executable communicates with the database, gathers data for all displayed windows, takes care of updates, and formats the reports. When started as a ClarioNET application this program runs hidden on the server....the screen display is not visible but the virtual screen still exists and is being used by the ClarioNET server side system. The Client application which is also a Windows executable program. This program contains no logic except the ability to create a complete user interface using instructions received from the server-side ClarioNET program. As a Windows program it has full access to normal Windows controls and resources such as local printers. When the ClarioNET client application is started it contacts the server via HTTP protocol and requests that the server run a particular application. The server then starts a new instance of the program and provides the client with an identifier so that it can be uniquely identified for future communication with the same instance of the server application.

How It Works
The server application will send the client encrypted, compressed data that describes the full structure of the windows and its controls and the data within the controls. The client is simply an intelligent assistant that receives instructions to render and manage a user interface. The user operates the client program EXACTLY as they would be running the program locally. The ClarioNET programming on client and server handle all user interactions and window updates throughout the session and for all aspects of the application running on the server. Once the application on the server is started and it opens a window, the Client then opens an identical window and controls. To the end user it appears that a normal Windows program executes...the only difference being a small colored hourglass indicator on the title bar which indicates when the client is communicating with the server. The largest transfer of data occurs when a new window is opened. To transfer the data to describe a typical window is between 1,000 to 9,000 bytes of data. After that only the instructions to update data are exchanged....usually less than 1,000 bytes per exchange (and most of the time less than 200 bytes!). ClarioNET does not use constant communication streams like other remote client products, helping to keep bandwidth requirements down and server activity to a minimum.

2 -Product Overview

If the user selects to print a report, the report is formatted and created as a WMF file on the server and sent to the client application. The client application can then display preview and/or directly send it to the local printer. This means the exact report that is designed for the application is what the client prints....a superior solution to browser-based report layout capabilities. As the client continues to open windows, manipulate controls, or create reports, these actions are executed on the server. Encrypted and compressed communications convey the results to the end user whose subsequent actions and new data are sent back to the server. When the end user shuts down the application, both the client program and the instance on the server are terminated. If the end user loses a connection, the server application is terminated when it reaches a timeout value set by the developer.

3 -Setup

3 -Setup
Running the Setup Program
To install ClarioNET you must have already installed Clarion Version 6.0 or later. We strongly recommend that you apply all patches (which are freely downloadable) from www.softvelocity.com to your copy of Clarion. Locate SETUP.EXE, double-click the icon, follow the directions, and read the README.TXT files to install ClarioNET. *

The setup program will back up your BUILTINS.CLW file and Note: replace it. If you have customized the BUILTINS.CLW file you must compare the old and new files to merge previous changes into the new file.

BUILTINS.CLW
The installation program backs up your existing BUILTINS.CLW file and replaces it with a modified one. Many Clarion standard procedures must be redirected to internal ClarioNET procedures to provide web usage. If for some reason you must manually update the BUILTINS.CLW file, the procedure is as follows: Load BUILTINS.CLW into the Clarion editor. Select File | Open and Navigate to the Clarion LIBSRC directory. Change the Files of type to Clarion source (*.clw; *.inc; *.trn). Select BUILTINS.CLW (You should now see this file in the text editor) Move the cursor to just below the MODULE Line. Select File | Import File, and select ClarioNET_BUILTINS.CLW file from the Clarion LIBSRC Directory. Save the file. Load an application and compile The compiler will report numerous Indistinguishable New Prototype Errors. This is expected because the old prototypes are still in the BUILTINS.CLW file. You need to comment out those lines. This is easily done as follows.... Press the [Edit] errors button. Press the [OK] button for the Edits made in generated source.. Warning dialog. The cursor will be placed at the source of the first error encountered. Turn the line to a comment by adding an exclamation (!) point just before the code that appears on the line.

3 -Setup

Use the [F4] key to find each successive error. Comment out each of these lines of code. Complete the modification by saving the modified BUILTINS.CLW. Recompile your application. The ClarioNET server extension DLL automatically detects when your application is running locally and simply sends the calls on to the standard Clarion procedures. When launched for web usage ClarioNET receives the procedure calls and stores the information internally for transmission and replication on the client.

Non-ABC Template Modifications Required

To add the ability for ClarioNET to support reports in a "Legacy" or "Clarion" template chain generated program there are two EMBED locations that need to be added to the REPORT.TPW template file.

Load REPORT.TPW into the Clarion editor. Select File | Open and navigate to the Clarion \template directory. Change the Files of type to Clarion All files (*.*).
Select REPORT.TPW. You should now see this file in the text editor.

Scroll down to about line 206. Immediately after the ACCEPT statement, add
the following template code:
#EMBED(%BeginningOfAcceptLoop,Beginning of ACCEPT Loop)

Go to about line 208. Immediately after the CASE EVENT() statement, add the
following template code:
#EMBED(%WithinEventProcessing,Event Processing for ACCEPT Loop)

NOTE: If the standard Clarion Legacy templates have been modified, the line numbers specified above will differ. Look for the mentioned code instead of line numbers.

Template Registry Setup

The installation program automatically registers the ClarioNET template. Should you need to manually register it, you will find the CLARIONET.TPL file in the TEMPLATE subdirectory.

Choose Setup | Template Registry from the Clarion Environment menubar. In the Template Registry dialog, press the [Register] button. In the Template File dialog, select the CLARIONET.TPL from the ..\template
subdirectory, then press ????.

3 -Setup

Press [Close] button after the template is registered.

Licensed vs. Trial Status

The ClarioNET programming package is supplied as a complete system. You can develop and deploy ClarioNET deployments of Clarion programs with ALL capabilities available. If you have not purchased a license and are using a as a demo download it operates in a "Demo" mode until you enter your ClarioNET Product Activation Code ( PAC ). When your ClarioNET license is purchased you are assigned a Product Activation Code (PAC) . You can enter this license password into the main template parameter screen -or-as the first parameter to the ClarioNETServer:Init procedure call. Demo mode creates a minimal impact...the client program will ALWAYS display a Unlicensed Demonstration Version banner as a starting window after launching the server based program and at regular intervals throughout the client session. A Demo application runs for 5 minutes before having to be restarted.

Files Installed
The SETUP.EXE installation program will install the following files in the locations shown. The directories noted refer to directories under the main Clarion install directory. \BIN CLRNT60S.DLL : Server side DLL that gives the ClarioNET functionality to your server application. LSCOMP.DLL : Server side DLL that provides data compression, encryption, and encoding for communicating with the ClarioNET client. Independent of Clarion version. \LIB CLRNT60S.LIB : Name resolution library for your server application to resolve the ClarioNET functions in the CLRNT60S.DLL file. CLNTSTUB.LIB : Name resolution library for your server application to resolve the ClarioNET functions. We have provided this for Third Party Developer usage. As 3rd parties add ClarioNET code permanently into their compiled DLLs they will ship this LIB file to resolve external names when ClarioNET is not licensed by the final end user.

3 -Setup
CLRNT60C.LIB : Client side static link library that contains all communication and functional code to communicate to the server based ClarioNET enhanced application. LSDECOMP.LIB : Client side static link library that contains data decompression and decoding procedures. PRNTPRVW.LIB : Client side static link library that contains the print preview system. This is the compiled prntprvw.prj project that is also supplied with this package. Please note: this print preview source code is provided for your convenience so you have print preview automatically in your client. You can replace this entire source code as needed \LIBSRC CLARIONET.CLW : Module definitions to be included in the server based applications global MAP. CLARIONET.INC : Class and type definitions for Server module. CLIENT.CLW : Module definitions to be included in the client side program that will call the ClarioNET client. CLIENT.INC : Class definitions and equates for client module \TEMPLATE CLARIONET.TPL : Template for web enabling your Clarion application using the ABC -or-legacy template. This template also includes provisions for 3rd party template generated code and will change as 3rd party support is improved or we receive information from them. \examples\clarionet\ (This directory contains subdirectories that contain example code.) \prntprvw PRNTPRVW.PRJ & PRNTPRVW.CLW : This is the source code for the ClarioNET client print preview procedures supplied as prntprvw.lib. You can modify the print preview system to suit your needs. \connect CONNECT60.PRJ & CONNECT60.CLW : Client side launching program shell that can be customized/replaced to provide your own specific startup interface to the ClarioNET client. Use the proper project file to match your Clarion version. CONNECT60.APP : Client side launching application for Clarion 5.5. \CNETDEMO

10

3 -Setup
Demonstration program \handcode HANDCODE.PRJ & HANDCODE.CLW : Simple example SERVER program in a single handcoded .CLW. file. \doc\ClarioNET CNET_60.PDF : Adobe Acrobat documentation for ClarioNET README.TXT : Contains the latest information on the most recent installation of the ClarioNET development system. Please read this information as it contains information not covered in this manual

11

3 -Setup

12

Applying ClarioNET To Your

Applying ClarioNET To Your Application

This section will describe how to add ClarioNET to your application using a template or by adding code to a hand coded application. The "guts" of adding ClarioNET is simply the addition of a few global procedure calls and five procedure calls within each Clarion procedure that opens and manages a window.

Applying the ClarioNET Template

After opening your application "APP" file apply the ClarioNET global template to your application: From the man Clarion menu select "Application" and then "Global Properties". Press the [Extensions] button. Press the [Insert] button. Highlight the ClarioNET(Server) extension and press [Select].. Enter your PAC in the entry provided. Change any of the template options (as described below) and press b to close the previously opened dialog boxes. Compile your application. Important ! The template needs to be added to ALL application files, including APP files that generate LIB and DLL modules. (Hand coded and 3rd party code must also be reviewed and ClarioNET calls included). For your Clarion application to run successfully on the web with ClarioNET, all procedures that display windows that require user interaction to close must have ClarioNET procedure calls added to them. Applying the template and recompiling will in most cases create a web enabled application ready for immediate testing. However, it is sometimes impossible for ClarioNET to locate every window or control that awaits user interaction in the embed code that you may have added to the template generated code. Therefore it is necessary to examine the behavior of all the windows, reports, and commands within your application to verify that they work properly. The next chapter will provide you with detailed information on the considerations you as a programmer must keep in mind so that you can convey all the functionality of a normal application to the remote user using ClarioNET.

13

Applying ClarioNET To Your Application

When compiling your server application, remember that it must be 32-bit standalone program.

ClarioNET in Hand Coded Applications

In a hand coded application you will be adding specific lines of program code to create data and call procedures. Please see the specific chapter later in this document. Before applying the template, you must add a define to your project: Press the [Project] button in the Application Tree dialog. Press the [Properties] button in the Project Properties dialog. Click the Defines tab. Add ClarioNETUsed to your defines. *

Many programs will appear to run, at first glance, without adding Note: the ClarioNETUsed define. You MUST add this define....it is possible that you will encounter problems when you explore your program running under ClarioNET. The POPUP, HELP, INI, ALERT, SELECT, and all graphics capabilities will not work unless this define is added.

Template Options
These options are visible when the ClarioNET template is highlighted in the "Extension & Control Properties" screen. If you are handcoding a ClarioNET Clarion program all of these items are available to you in source code area. Please see the specific handcode section for this information. Enable ClarioNET This checkbox enables or disables the inclusion of ClarioNET code in your ABC or Clarion (legacy) generated application. Product Activation Code ( PAC ) This password is provided with your purchased copy of ClarioNET. The ClarioNET programming package is supplied as a complete system and will operate in "Demonstration" mode until a valid PAC is entered. Without a valid PAC an "Unlicensed Demo Version" message will appear when the client connects.

14

Applying ClarioNET To Your

*

All of the functionality is available without entering a License Password...this is called Trial mode. You can use it to completely develop your web enabled application or test a conversion of an existing application. This is useful to show work in progress to a client, provide a web demo to prospects, or just to educate yourself of the groundbreaking capabilities of ClarioNET.

Hand coders need to enter the valid PAC as the first parameter to the ClarioNETServer:Init function. Application Visible on Server This flag enables display of the running application on the server. You should always set this to Off for a deployment build. Using this option to display the screen on the server allows you to see messages that Clarion is displaying that prevent the application from starting. These messages range from missing DLL's, unable to open files, etc that occur BEFORE the ClarioNET system is initiated. It is extremely helpful when becoming familiar with server deployment -and- to view the behavior of the program if something does not look quite right on the client. The two should be identical. *

The ISAPI version of the Application Broker inherently prevents any screen display from a running application launched through the ISAPI extension.

Windows HELP Sent to Client ClarioNET has the ability to transfer your standard Windows HLP files to the client and display them automatically using typical Clarion syntax. Check this box to enable HELP functionality. ClarioNET:EnableHelp(1) will be added to your program_name.CLW. file. Call to the HELP procedure is redirected to an internal ClarioNET function (thanks to the new prototypes in the BUILTINS.CLW file) which send the instruction to the client. You can use ClarioNET:EnableHelp method to change this behavior at any time. INI Files Default to Client ClarioNET has the ability to automatically redirect all GETINI and PUTINI calls to the client. Check this box to enable this redirection. Investigate this option before turning it on.....it is possible for numerous INI calls to be made that will severely effect the performance of your program because of network lag time. Reports Use a Progress Bar You have the option of enabling a Progress Bar on the client while a report is being generated. Checking this item send a message to the client at intervals during report creation when the progress thermometer value reaches 7% intervals. A maximum of 14 updates will happen to the client progress bar during a report generation process. In

15 Applying ClarioNET To Your Application

general, only use a progress bar for reports expected to exceed 100 pages because printing speed will be effected for small reports. Implement as Continuous Connection By default ClarioNET detects user inactivity so that it can shut itself down automatically to free server resources. Continuous Connection can be used for always-on systems, such as point-of-sale or equipment monitoring systems. Using "Continuous Connection" means that as long as the client program is running it will contact the server program at regular intervals to tell it Im still here...dont shut down. *

Note: The Server Auto Shutdown time will still be used in case the client stops automatically responding to the server, as in the case of a client location computer hang, power outage, or Internet service interruption.

Client Refresh Interval (minutes) (Used with Continuous Connection). This specifies the time interval for the client to automatically send the server a message. A message will be sent every Client Refresh Interval minutes to tell it that the client is still alive. Client Auto Shut Down This value is the number of minutes the Client will wait for any type of user activity (keypress, mouse control selection, etc.) before automatically shutting down both the server and client programs. For example, if the end user forgets to exit the program (goes off to lunch or leaves for the day). It is good practice to have it shut down so as not to consume server resources. A value of zero (0) disables the inactivity check. *

Note: The Client shut down time must always be less than the server shut down time. If your entries specify otherwise the Server Auto Shut Down time will be internally set to one minute longer than the Client Auto Shut Down time.

Throughout the ClarioNET session the server program waits for client commands. The server has no way to tell the client it is shutting down. By setting the client time shorter than the server time the client will always shut down first. The server time is only used when the client and server have lost contact and the server program must shut itself down to rid the server of a hung program instance. Server Auto Shut Down This value is the number of minutes the server will wait for any type of contact from the client before posting a HALT() command. Normally the Client will automatically send a signal to the server at time intervals equal to (Client Auto Shut Down Time / 3) to tell the server program that the client is still alive. If the Client program ceases to continue functioning the server will not receive these

16

Applying ClarioNET To Your

signals. When no signal has been received for longer than the minute value specified, the server program will shut itself down. A value of zero (0) disables the inactivity check. Use ABC Toolbar Clarion ABC programs offer the option of using a toolbar and/or buttons to control listbox behavior. For thread and window management purposes, in ClarioNET the Button window design is more efficient and reliable than the Toolbar design. In a strictly local execution of a program Clarion uses MDI to route toolbar events to procedures. Web applications cannot use MDI, and so ClarioNET must duplicate the toolbar on each window. This is a complex process, made harder because the template must automatically detect when a toolbar is to be used. CPCS Report Generation Compatibility Server This flag signals the template to generate slightly different code into REPORT procedures that are generated with the CPCS templates that contain their own unique template identification. *

It is imperative that no windows are present in CPCS reports that Note: require user interaction. The PREVIEW attribute on reports (or the equivalent property assignment) must always be used. DO NOT PERFORM WINDOWED PRINT PREVIEW IN THE SERVER PROGRAM.

LoadStar RPM Templates Compatibility This flag signals the template to generate slightly different code for use with these templates.

17

Applying ClarioNET To Your Application

18

Program Design Considerations

Program Design Considerations

Introduction
In general, the internal workings of a Clarion application make separating the user interface from the application quite simple. Clarion programs create controls, customize their appearance, and fill them with data before displaying them on screen. The complete description of a window is a simple data structure. ClarioNET replicates the WINDOW and APPLICATION data structures on the client by scanning each window immediately after it is OPENed. The client then uses CREATE program statements to build a local copy of each WINDOW which is identical to the one on the server. The client then begins its ACCEPT loop, and transfers any messages regarding user interaction back to the server based program. The server processes these events, keypresses, and data changes, and sends back just the changes to the data structures to the client. The client again asks the local copy of Windows to make any changes to the relevant controls. If you understand this it should be easy to debug any programs that youve applied the ClarioNET template to. Keeping this workflow in mind when you create new applications will enable you to easily design new programs with ClarioNET in mind as an option, whether you implement the new application as a ClarioNET application or a normal desktop application. In general, just about everything in wizard-generated template code transfers to ClarioNET without modification. Any logic that you place in embeds should also transfer easily providing you observe the basic design guidelines (see next section). Any user interface code that you place in embed code that creates windows, utilizes timers, or awaits user interaction, however, will need to be checked. The ClarioNET template generally finds all the user interface code in the windows and reports that the templates generate, but it cant always guarantee the same for your embeds.

Design Guidelines
These items should be carefully checked during your program design stage to avoid hard to find problems in the later stages of development. *

IMPORTANT ! It is ESSENTIAL these design guidelines below are followed before you test or deploy your ClarioNET web enabled program.

If your program will operate both as a native EXE program and web deployed with ClarioNET you can use the ClarioNET procedure ClarioNETServer:Active() to test if the application is running under ClarioNET. Add ClarioNETUsed as a project define.

19 Program Design Considerations

 Make the required source code changes to BUILTINS.CLW. Disable all Edit In Place usage. This is automatically done for you in the ABC templates. Disable or remove all ABC Query By Example (QBE) usage (the ABC classes

create complete windows for QBE control at runtime that are not manageable by ClarioNET without rewriting the ABC classes).
Your server program must be compiled as StandAlone so that it uses the Clarion runtime DLL's and ClarioNET server side DLL's. Your client program must be compiled in Local mode. This was decided upon because the "thin client" design requires minimal impact on the client computer. Local mode creates one single EXE file. All controls in WINDOW and APPLICATION structures must have non-duplicate USE attributes. If you need to add them you can use a dummy field equate label. Your application will run as Single Document Interface (SDI). Make sure your program is designed or modified to run properly as a SDI program by checking the expected results from START and POST Clarion statements. Do not allow ANY processing or procedures calls to be performed on EVENT:Timer. For best results controls should have X, Y, Width and Height specified. Disable Clarions INI file strategy of saving window sizes in INI files. Do not use windows in report procedures. Gather all data needed to generate a report THEN call the procedure that generates the report. Always use the PREVIEW attribute on reports. The following limits to screen controls should be checked: a) Maximum of 60 total LIST and COMBO controls per window. b) Maximum of 200 fields in a LIST QUEUE. c) Maximum of 1000 total ENTRY, SPIN, CHECK, SHEET, OPTION, PROGRESS, ITEM, LIST and COMBO controls per WINDOW. d) Maximum of 25 TEXT controls per window. e) Maximum of 40 ICONs within each LIST control. f) Maximum of 75 ALRT keys per window and per control. No aggregate limit. g) After opening and closing the first APPLICATION or WINDOW you can not use another. ClarioNET is designed assuming the server program will exit after the first top level window is closed. Both Client and Server programs must be 32 bit.

20

Program Design Considerations

Disable all Drag & Drop usage. Disable or remove all OCX controls. Delete Clarion Internet Connect or Web Builder templates from the application. Do not use EVENT:Last 3 to EVENT:Last Use ClarioNETWindow.MouseX and ClarioNETWindow.MouseY to inspect mouse locations on the client window when an action took place. Windows API calls are not transferred through to client. Disable all calls to write to the window, play sounds, etc.. If runtime tabbing order changes are used with a PROP:Follows assignment, substitute a call to CLARIONET:SetPropFollows. The client ClarioNET library requires Microsoft WININET.DLL to provide the HTTP communication capability.

Defines
Always add "ClarioNETUsed" as a project define. *

Note: Many programs will appear to run, at first glance, without adding the ClarioNETUsed define. You must still add the define, for its possible that you will encounter problems when you explore your program running under ClarioNET further.

Window Management
Your program running on the server is using the Client as the user interface. The two must always be aligned, that is the client is displaying the window exactly as it exists on the server. Most of this is automatic however you must keep in mind: Hidden BREAK commands that exit a Windows ACCEPT loop without posting an EVENT:CloseWindow will misalign the client and server. Replace BREAK from a window with POST(EVENT:CloseWindow). Do not use TIMER events to call procedures that open windows or call any ClarioNET procedures. Your program cannot use Multiple Document Interface (MDI). This is a restriction placed on the program by the Clarion Application Broker. ClarioNET uses the property assignment SYSTEM{PROP:Threading} = 0 to forcefully turn off threading capability.

21

Program Design Considerations

INI File Management

In general, you will probably prefer to store .INI files on the client to tailor the application specifically to the connected user. You can easily do this in the ClarioNET template options in the global template. If you choose to store the .INI file on the server, please turn off Clarion's ability to store window positioning due to the possibility of differing screen resolutions from session to session. It is possible that a client may run the application on a 1024 by 768 desktop, close the application in the lower right hand corner of that desktop, and then the next user tries to run it from a 640 by 480 desktop. That user may wonder where the window is. *

Warning ! If you choose to send all INI file access to the client your programs performance could suffer badly. Please test first and check your source code for potentially numerous INI calls. It might be easier to send small configuration files between client and server at startup.

Help Files
ClarioNET supports Windows help that is implemented in Clarion using the HELP() statement to specify the help file to be used. ClarioNET redefines the HELP Clarion procedure prototype to ClarioNETs own internal procedure. When your application is not being used in ClarioNET mode the standard Clarion help system on the local computer will be used. ClarioNET supports help by transferring the entire HELP file to the client along with the HLP attributes on all screen controls. The help file is transferred at startup and, if your server application has specified a new help, when the client window is being updated. The help file on the client follows the same usage as the icon and image files. *

Note : All files are loaded from server to client once and are deleted when the client worksession is complete.

Because the entire help file is sent to the client, it is strongly recommended that you keep the help file(s) small. You can use multiple calls to HELP in your application to bring the proper one of multiple .HLP files into scope. The file is only sent once during a session; repeated calls will not cause another file transfer. In a hand coded program you must explicitly add a line of code to enable help, at the start of your application, following ClarioNETServer:Init :

22

Program Design Considerations

ClarioNET:EnableHelp( SHORT Mode),SHORT This function turns on and off the help system usage. The Mode parameter should be 1 to enable the transfer of the help file to the client and 0 to prevent the transfer of the help file to the client. This also effects the call to HELP

without parameters!

Graphics Statements
ClarioNET supports all Clarion graphic language statements: ARC, BLANK, BOX, LINE, CHORD, ELLIPSE, ROUNDBOX, SHOW, TYPE, PIE, POLY and IMAGE. This is done by redirecting the standard Clarion graphics calls to ClarioNET procedures by using the ClarioNETUsed define and the revisions to the BUILTINS.CLW file. ClarioNET automatically detects whether the application is running on a local desktop or was launched by a remote ClarioNET client and will redirect the graphics as needed (graphics sent to reports are not effected). Windows API calls that draw to the window are not captured.

Security
There are three general areas of security for consideration: encryption, user access, and server access. Encryption All communications between client and server are encrypted with 128 bit "Blowfish" method encryption. In addition the data streams are compressed with a proprietary compression algorithm and also MIME encoded for more reliable TCP/IP communication. User Access Although ClarioNET encrypts the data, it cannot prevent remote users from leaving client programs available on their desktop which, with just a double-click, can be used to access the data by anyone passing by. We encourage you to add a password procedure to the client application. By initially disabling the Connect button before password verification you can prevent initial unauthorized access. In this case you will probably not want to store user IDs and passwords in a data file, which would then have to be downloaded to the client along with the drivers. An alternative would be to store user IDs and passwords in an array in the client EXE and check against that as a simple and straightforward first line of protection.

23

Program Design Considerations

Server Access We strongly encourage you to build password checking into the server side application. Because the client cannot access any data files on the server unless you specifically download them to the client with code in the server program, its simple enough to use a local data file for verification of access rights. This also allows you to collect the user ID and password to forward to the database server.

User Interface Considerations

In general, the end user will perceive a ClarioNET application no differently than a normal Windows application. You can design the windows for your applications the same as a normal application. Display of normal windows and report components will be very quick, resulting in an application with a very fast feel.

Application Design
You are in charge of the application programs design. Because there will be 50 or so copies of the same application running on the server at one time each coding efficiency or coding mistake will be magnified 50 times. ALWAYS be thinking about these items: Execution speed for a given user event The efficiency of the program from the users perspective is how quickly their actions are completed. Aim for less than one second. Thoroughly examine your file usage Use a fast and large caching disk controller. Test your queries and VIEWs and tune them for the usage. Huge queries will effect all users on your server. Examine using a separate DBMS server. Memory usage Dont hog RAMyou will be taking it from all the other instances of your program. Limit use of INI files on the client .each PUT or GET requires a round-trip. Put more controls on a screen ClarioNET and Clarion can handle huge screens.1,500 controls are common. Doing this and hiding/unhiding groups or tabs is far faster than constantly sending new small screens. The time to scan, compress, send, uncompress, and build one screen on the client is small compared to opening and closing many windows. Use larger QUEUES for LISTs Constant LIST updates because of small QUEUE record counts requires more round trips. Because ClarioNET uses advanced compression it is faster to use larger data sets.

24 Program Design Considerations

 Always put most of the functionality into DLLs Because the DLL is only loaded once and your EXE is loaded once for each new instance you can be far more memory efficient using DLLs. Examine your LOOP processes thoroughly For example, using the INSTRING procedure is notoriously slow compared to using string slicing in a loop. Adding many bitmapped graphics to your windows adds to the amount of information that the end user will need to download before displaying the window. ClarioNET compression is good, but be sure to test performance over the type of connection you expect your remote users to use when using many IMAGEs. Always try to precompress GIF and JPG graphics with a good compression tool like uLead Smart Saver. Your end users may be running in different resolutions and have different fonts on their systems. Try to keep your windows from growing overly large, and stick to basic fonts such as Arial, Times New Roman, and MS Sans Serif. Because MDI is not supported in ClarioNET, consider redesigning those applications where users typically open several browses during the normal course of work. Providing thin client versions of your application is often a good opportunity to discuss with your end users the creation of a cleaner redesign of existing applications. Many Clarion applications began life as DOS applications, and when ported to Windows, developers minimized interface changes to maintain familiarity for experienced users.

Reviewing Source Code Procedures

We strongly encourage you to review your source code module by module, specifying that the development environment show you all filled embed points. This will allow you to identify any windows, timers, or other user interface features which were not template generated. Clarion makes it easy to do this. You may select the Category tab in the application tree to view all source code type procedures. You can just right-click each, choose Source, and then review all your code. Additionally, you can check any procedure by double-clicking the procedure to view its properties dialog, pressing the Embed button to view embed code, and then the [Show Filled Only] button to see only those embeds that have custom code attached. When creating future projects, we encourage you to create procedures for every window using templates, and calling the procedure whenever you wish to open that window, so that all your user interface elements will be accessible to ClarioNET. In other words, dont put WINDOW structures in source code.

25

Program Design Considerations

Controls That Do Not Appear Running via ClarioNET

Any time a control appears in your application running locally BUT DOES NOT appear in a ClarioNET client, the first item to check is that the control contains a unique field equate label. For example: USE(?Label1) Each control MUST have a USE variable otherwise the ClarioNET client will not receive enough information to duplicate the control correctly. Also...all field equate labels MUST BE UNIQUE. If you get a compiler error that says "Duplicate label" stop right there and make sure all WINDOW or APPLICATION controls have unique USE variables. Menus (in particular those imported from older DOS applications) may lack USE attributes. TAB controls should also be checked carefully.

26

Reports in ClarioNET

Reports in ClarioNET
When Clarion was first developed, the developers copied a printing feature which was specific to Windows NT at that time. This involved creating a Windows WMF metafile, which is a series of instructions to the Windows GDI (Graphics Device Interface) that describes how Windows should draw the elements on a page. (This is not a generic page description language like postscript) These instructions, in conjunction with the device settings and driver for the printer, allow Windows to provide complete instructions to the printer to create a complex report. When your program creates a report it is done on the server and ClarioNET must capture and transfer it to the client. WMF files are created when the PREVIEW attribute is implemented for a report, which is why you must always enable print preview in your ClarioNET applications. ClarioNET compresses and encrypts the metafile (WMF file) created on the server and sends it to the client. The client places the received metafiles on the client disk and calls the Print Preview procedure (supplied to you as source code) to display the WMF. Depending on the user's selection the metafiles are then sent to the local printer driver and then on to the locally connected printer. Because just the GDI instructions for the report are sent to the client, and they are highly compressible, this provides for highly efficient communication speed and complete support for reports as designed. Server Printing Setup Considerations Before a metafile can be generated correctly, Windows must have a device that is capable of printing . It needs to be know page size and other parameters that will govern the creation of the WMF. If not Windows will print to the default device....the screen console....and it will be bad indeed. *

Note ! You must install a printer on the server, even if you do not intend to physically connect any printer at all to the server.

In general, we recommend installing an industry standard driver such as the HP LaserJet Series II, or any of the HP Postscript drivers. The servers printer driver should be able to support any size of paper or device options (such as color) that you wish to define for any of your reports. Remember....you are not actually printing to a printer. You are depending on the printer driver to support as much output capability as possible so that a rich WMF file can be created. When it is finally printed on the client's computer it will be the job of that printer driver to reduce printout complexity as needed. You can immediately spot if there is a printer device driver problem of lack thereof: the lower portions of the page will not print. The ClarioNET client attempts to fit this odd size GDI drawing into the common paper size selected and cant. All it can do is try to compensate by not cutting off the right side of the report, but it cannot compensate enough to print the rest of the report properly.

27

Reports in ClarioNET

NOTE : There are additional very important instructions in the chapter entitled Server Setup which specifically apply to ISAPI deployment. Microsoft Internet Information Server (IIS) handles the printer device differently than Application Broker.

ClarioNET Server Side Report Programming

The ClarioNET server side extensions to the printing program code add calls to display a message on the client, optionally update a progress bar, manage the WMF filenames, add the WMF names to an internal QUEUE, send report properties to internal variables, and then send the report to the client. *

Do not execute visual Print Preview of your report in the server Note: side code. If you need this ability in the local version, use ClarioNETServer:Active() to test if ClarioNET is handling the user interface and skip around the code. The template does this automatically in standard ABC and Legacy reports.

Although Report Preview mode must be enabled in your program (using the PREVIEW attribute on the report) to generate the WMF files, the actual visual report previewing code must be disabled (the template code does this for you). If you use third party tools you must disable server side previewing and add your third party code to replace the supplied previewer code in the client. Performance Tip..... Clarion ABC and Legacy templates both control printing by opening a progress window with a TIMER attribute which is set 1. This means a timer event is generated every 1/100th of a second. The report generation process is driven by these timer events, processing one record per timer event and triggering PROGRESS window updating. *

This is extremely inefficient.....it limits the program to processing just 100 records per second.

For very large reports you may wish to rewrite the procedure to eliminate the timer generated process which can cause performance degradation and consume server processing time in an environment where the processor is shared among many instances of a program. Plan on testing. Client Side Report Processing The WMF metafile created for your printout is almost, but not completely, device independent. Therefore, we cannot guarantee there will never be printing incompatibilities

28

Reports in ClarioNET
between server printer and client printer. In general, following these guidelines should minimize any problems: Be sure that both the server and the client have printer drivers installed that can print the size of the paper specified in the report. If you need to specify manual feed, or other device specific settings, instruct your users to use the Printer Setup dialog on the client. PRINTERDIALOG calls are redirected to the client. When both a Microsoft or OEM driver is available for a printer, choose the OEM driver, unless the OEM driver is very old and hasnt been updated in years. Do not expect perfect output on old or oddball equipment. In general, test all reports thoroughly with the printer the reports are to be printed on. Disabling Client Side Empty Report Message The property ClarioNET:Global.DisplayClientEmptyReportMessage is used to control the automatic display of a client side message when a report generates no pages (or WMF files). Set ClarioNET:Global.DisplayClientEmptyReportMessage to 1 to enable the display, 0 to disable.

Overview of Report Processing Procedures

The following is a brief review of the ClarioNET procedures used to capture the Clarion generated WMF files and send them to the client. To see how these are used you can review the Hand Code section of this documentation. Report{PROP:TempNameFunc} = ADDRESS(ClarioNET:GetPrintFileName) This statement allows ClarioNET to generate its own filenames for the WMF files generated by the report. All subsequent calls by internal Clarion routines to get WMF names are routed to this function. ClarioNET erases these files automatically after they are sent to the client. ClarioNET:StartReport This method is called near the starting point of the report. It causes a Generating Report window to appear on the client. The client then waits for the server to start transmission of the WMF report files. ClarioNET:UpdateReportProgress(BYTE Pct)

29

Reports in ClarioNET

This method creates a progress bar on the Generating Report window that is being displayed on the client. The progress bar is displayed on the first call and the percentage complete (Pct) is updated on each subsequent call. The progress bar percentage on the client is only sent at 7% increments to minimize bandwidth (regardless of how many times you call this procedure). Pct represents the percentage of report completion. This value ranges from 0 to 100. *

Note! Only use this for long reporting processes. Because of the server->client->server communication it can cause small reports to print much slower.

ClarioNET:EndReport This procedure is called after the report is prepared, ClarioNET has been notified of the WMF file names and the report properties have been set. It is preferable that this should be the LAST procedure called before exiting the REPORT procedure and returning to the calling procedure. When this procedure is called the following tasks take place: The client is notified that it will be receiving the report WMF files in compressed form. The client closes the Generating Report status window and opens the Downloading Report status window. The server side prepares and sends a compressed file containing al the WMF files to the client and waits until the client side printing process is finished. The client side receives the compressed file, uncompresses it, places the WMF files into the client temporary directory, and calls the ReportPreview procedure. *

The server program will be waiting for the client to finish printing Note: before program execution after ClarioNET:EndReport continues. This means that while the user is reviewing the report in the ReportPreview procedure and while the report is printing on the client (or being sent to a spooler) the server program is waiting. This is necessary because the server program could execute other code that sends commands to the client and it would not be listeningit still would be managing the printing process.

ClarioNET:GetPrintFileName(SIGNED PageNo) This procedure is added to the main application CLW file and is used as a call point for the ClarioNET:GeneratePrintFileName procedure from anywhere in your application.

ClarioNET:AddMetafileName(STRING Filename)
This procedures assigns the WMF filenames to an internal ClarioNET QUEUE for use by the EndReport procedure.

30

Reports in ClarioNET
ClarioNET:SetReportProperties(REPORT) This procedure sends the report structure, which must not be closed, to ClarioNET so the properties can be scanned and sent to the client. This includes landscape, paper size, measurement type, etc. ClarioNET:UseReportPreview(SHORT Flag) This procedure can disable/enable calling the ReportPreview procedure on the client side. Flag = 0 for no preview, non-zero for previewing.

31

Reports in ClarioNET

32

How to Transfer Files

How to Transfer Files

ClarioNET allows you to transfer files in both directions....server to client and client to server. You can send one or multiple files with each call....the filenames are loaded into a QUEUE for internal processing. Transfers can be done via the HTTP datastream or a separate FTP server. *

In addition to the multi-file Server->Client and Client->Server transfers there is a special client-side only procedure named ClarioNET:GetFTPFile which can be used before a ClarioNET has been started.

There are two important items to remember: Implementing file transfer involves using two matching procedures...one on the server side and one on the client side. First you call a server side procedure, then a client side procedure is called and return a value, and the server side procedure receives the return value. Any file transfers must be defined by knowing the fully qualified path of the source file. This can be hard coded name or a variable. NOTE ! IN all examples that follow you can direct the client to use "PASSIVE" FTP mode by appending "/passive" to the IP address. For example: '208.36.30.226/passive'. ALL file transfers use a QUEUE defined in the CLRNT60S.DLL or CLRNT60C.LIB ClarioNET code libraries. It is defined as follows: FileListQueue Filename QUEUE,PRE(FLQ),EXTERNAL STRING(512) END

Server to Client File Transfers using HTTP

Sending a file from the server application to the client computer using HTTP involves these steps: (1) Load the name of the file or files to send into a queue. It is not necessary to free the QUEUE...it will not contain any records because any prior usage will have FREEd it. Here we will specify two files: FLQ:FileName = c:\cwicweb\public\PurchaseOrder.PDF ADD(FileListQueue) FLQ:FileName = c:\cwicweb\public\PriceSheet.PDF ADD(FileListQueue) (2) Call ClarioNET procedure to transfer the file ClarioNET:SendFilesToClient(SHORT Flag, <SHORT DisplayFlag>),STRING

33

How to Transfer Files

Flag : This value will be sent through to the procedure on the client (see next) . It is a user defined flag that is sent to the client side procedure once all files have been transferred. Use it any way you choose. DisplayFlag : Controls display of the file transfer progress window on the client. Set to non-zero (the default for an OMITTED parameter) to turn display on, or set to zero (0) to turn off. Return Value : STRING(255) This will be the value returned from the client side procedure (see below). (2) Modify the Client Side procedure. After you call the procedure described in (2) above all of the files in FileListQueue will be transferred to the client. When transfer is finished the client side procedure ClarioNET:ClientFilesReceivedFromServer is called. When files are received from the server, the FileListQueue field FLQ:Filename has the complete file specification on the client where the received files have been placed. By default these are always placed in the Temporary directory that was used or specified at client startup. You should move or erase these files as needed. ClarioNET:ClientFilesReceivedFromServer(SIGNED Flag),STRING Flag : This value will be the parameter of the server procedure ClarioNET:SendFilesToClient. Return Value : STRING(255). This value will be returned to ClarioNET:SendFilesToClient. The ClarioNET client will call ClarioNET:ClientFilesReceivedFromServer after the file transfer is complete. This procedure (which you must write) is responsible for examining the FileListQueue and determine what to do with the files received. FileListQueue will be FREEd immediately after returning from this procedure. You do not need to FREE it yourself. *

Note! If one of the files was not able to be transferred to the client its name will be proceeded by 0: in FileListQueue.

Server to Client File Transfers using FTP

Sending a file from the server application to the client computer using HTTP involves these steps: (1) Load the name of the file or files to send into a queue. It is not necessary to free the QUEUE...it will not contain any records because any prior usage will have FREEd it. Here we will specify two files: FLQ:FileName = c:\cwicweb\public\PurchaseOrder.PDF ADD(FileListQueue)

34

How to Transfer Files

FLQ:FileName = c:\cwicweb\public\PriceSheet.PDF ADD(FileListQueue) (2) Call ClarioNET procedure to transfer the file ClarioNET:SendFilesToClient(SIGNED Flag, <SHORT DisplayFlag>, STRING ServerName, USHORT ServerPort, STRING UserName, STRING Password, STRING ServerDirectory) Flag : This value will be sent through to the procedure on the client (see next) . It is a user defined flag that is sent to the client side procedure once all files have been transferred. Use it any way you choose. DisplayFlag : Controls display of the file transfer progress window on the client. Set to non-zero (the default for an OMITTED parameter) to turn display on, or set to zero (0) to turn off. ServerName : Name of the server to use for FTP, i.e. Www.clarionet.com -or-xxx.xxx.xxx.xxx. ServerPort : Port to use for FTP. Defaults to 21 is left as 0. UserName : Login name to use to log onto FTP server. Password : Password to use to login to FTP server. ServerDirectory : Subdirectorry to log to. I.e. \updates. Return Value : STRING(255) This will be the value returned from the client side procedure (see below).

(3) Modify the Client Side procedure. After you call the procedure described in (2) above all of the files in FileListQueue will be transferred to the client. When transfer is finished the client side procedure ClarioNET:ClientFilesReceivedFromServer is called. When files are received from the server, the FileListQueue field FLQ:Filename has the complete file specification on the client where the received files have been placed. By default these are always placed in the Temporary directory that was used or specified at client startup. You should move or erase these files as needed. ClarioNET:ClientFilesReceivedFromServer(SIGNED Flag),STRING Flag : This value will be the parameter of the server procedure ClarioNET:SendFilesToClient. Return Value : STRING(255). This value will be returned to ClarioNET:SendFilesToClient.

How to Transfe35r Files

How to Transfer Files

The ClarioNET client will call ClarioNET:ClientFilesReceivedFromServer after the file transfer is complete. This procedure (which you must write) is responsible for examining the FileListQueue and determine what to do with the files received. FileListQueue will be FREEd immediately after returning from this procedure. You do not need to FREE it yourself. *

Note! If one of the files was not able to be transferred to the client its name will be proceeded by 0: in FileListQueue.

Client to Server File Transfers using HTTP

*

Note : The HTTP method of transmitting files from client to server is SLOW because it requires many client/server/client conversations. We recommend using the FTP version for client->server file transfers. When using the HTTP version keep file size as small as possible.

Sending a file from the server application to the client computer using HTTP involves these steps: (1) Call the ClarioNET procedure to request files from the client. This procedure allows you to send a numeric "flag" and also a STRING to the client side procedure ClarioNET:GetFilesFromClient(SHORT Flag, STRING Info, <SHORT DisplayFlag>) Flag : This value will be sent through to the client side procedure ClarioNET:SendClientFilesToServer (see below). Info : This string (maximum 1024 chars) will be sent through to the client side procedure ClarioNET:SendClientFilesToServer (see below). DisplayFlag : Set to non-zero to display the progress window on the client. If parameter is OMITTED then progress window is displayed.

(2) On the client side load the files to be transferred. After calling the procedure in (1) above your request is sent through to the client side. The client side procedure ClarioNET:SendClientFilesToServer is called with your Flag and Info parameter. YOU then must do whatever is needed to load the filenames into FileListQueue so they are identified. ClarioNET:SendClientFilesToServer(SIGNED Flag, STRING Info) Flag : This value will be the parameter of the server procedure ClarioNET:GetFilesFromClient. Info : This string will be the parameter of the server procedure ClarioNET:GetFilesFromClient.

36

How to Transfer Files

Returns : STRING(255). This value will also be the return value from your call to ClarioNET:GetFilesFromClient. Within this procedure you can do anything required to load the filenames into FileListQueue......use static names, read a file, or display a FILEDIALOG that the client will use. Here is a code sample of the client side procedure to assign files names to FileListQueue to be transferred to the server. ! ClarioNET:SendClientFilesToServer PROCEDURE(SHORT Flag, STRING ServerFileInfo, <SHORT DisplayFlag) ! FileList STRING(5000) Extension STRING(*.*) PathName CSTRING(FILE:MaxFilePath) Pos1 SHORT Pos2 SHORT CODE FREE(FileListQueue) RetVal# = FILEDIALOG(Select Files To Send, FileList, Extension, 11000b) IF RetVal# = 0 THEN RETURN(no files selected) END Pos1 = INSTRING(|, FileList, 1, 1) IF Pos1 = 0 FLQ:Filename = CLIP(FileList) ADD(FileListQueue) ELSE PathName = FileList[1 : Pos1-1] & \ LOOP Pos2 = INSTRING(|, FileList, 1, Pos1+1) IF Pos2 = 0 FLQ:Filename = PathName & FileList[Pos1+1 : Pos2 -1] ADD(FileListQueue) Pos1 = Pos2 ELSE Pos2 = LEN(CLIP(FileList)) FLQ:Filename = PathName & FileList[Pos1+1 : Pos2] ADD(FileListQueue) BREAK END END END RETURN(ok) After the files are added to FileListQueue you can return a STRIG from this procedure that will be the return string of the server side ClarioNET:GetFilesFromClient procedure.

37

How to Transfer Files

(3) Inspect return value and FileList Queue. When the ClarioNET:GetFIlesFromClient procedure returns the file transfer operation has been completed. Upon receipt of the files, the server applications QUEUE will contain the fully qualified file specification. In this example the ClarioNET:GetFilesFromClient procedure will receive ok as the return value. The server program must move or delete the file(s) as necessary and FREE the QUEUE. Note that after a normal session closedown the files on the server will be deleted. The files received are ALWAYS initially placed in the temporary work directory for the program instance, which is a subdirectory of the "Public" directory. Your server program must move and delete them as needed and FREE the QUEUE. It is not really required to delete them as they will be deleted from the temporary directory automatically when the session terminates, but is recommended as good housekeeping practice. *

Note! If one of the files was not able to be transferred to the client its name will be proceeded by 0: in FileListQueue.

Client to Server File Transfers using FTP

Sending a file from the server application to the client computer using FTP involves these steps: (1) Call the ClarioNET procedure to request files from the client. THIS procedure allows you to send a numeric "flag" and also a STRING to the client side procedure ClarioNET:GetFilesFromClient(SIGNED Flag, STRING Info, <SHORT DisplayFlag>, STRING ServerName, USHORT ServerPort, STRING UserName, STRING Password, STRING ServerDirectory) Flag : This value will be sent through to the client side procedure ClarioNET:SendClientFilesToServer (see below). Info : This string (maximum 1024 chars) will be sent through to the client side procedure ClarioNET:SendClientFilesToServer (see below). ServerName : Name of the server to use for FTP, i.e. Www.clarionet.com -or-xxx.xxx.xxx.xxx. ServerPort : Port to use for FTP. Defaults to 21 is left as 0. UserName : Login name to use to log onto FTP server. Password : Password to use to login to FTP server. ServerDirectory : Subdirectorry to log to. I.e. \updates.

38

How to Transfer Files

Return Value : STRING(255) This will be the value returned from the client side procedure (see below).

(2) On the client side load the files to be transferred. After calling the procedure in (1) above your request is sent through to the client side. The client side procedure ClarioNET:SendClientFilesToServer is called with your Flag and Info parameter. YOU then must do whatever is needed to load the filenames into FileListQueue so they are identified. ClarioNET:SendClientFilesToServer(SIGNED Flag, STRING Info) Flag : This value will be the parameter of the server procedure ClarioNET:GetFilesFromClient. Info : This string will be the parameter of the server procedure ClarioNET:GetFilesFromClient. Returns : STRING(255). This value will also be the return value from your call to ClarioNET:GetFilesFromClient. Within this procedure you can do anything required to load the filenames into FileListQueue......use static names, read a file, or display a FILEDIALOG that the client will use. Here is a code sample of the client side procedure to assign files names to FileListQueue to be transferred to the server. ! ClarioNET:SendClientFilesToServer PROCEDURE(SHORT Flag, STRING ServerFileInfo, <SHORT DisplayFlag) ! FileList STRING(5000) Extension STRING(*.*) PathName CSTRING(FILE:MaxFilePath) SHORT Pos1 SHORT Pos2 CODE FREE(FileListQueue) RetVal# = FILEDIALOG(Select Files To Send, FileList, Extension, 11000b) IF RetVal# = 0 THEN RETURN(no files selected) END Pos1 = INSTRING(|, FileList, 1, 1) IF Pos1 = 0 FLQ:Filename = CLIP(FileList) ADD(FileListQueue) 39

How to Transfer Files

ELSE PathName = FileList[1 : Pos1-1] & \ LOOP Pos2 = INSTRING(|, FileList, 1, Pos1+1) IF Pos2 = 0 FLQ:Filename = PathName & FileList[Pos1+1 : Pos2 -1] ADD(FileListQueue) Pos1 = Pos2 ELSE Pos2 = LEN(CLIP(FileList)) FLQ:Filename = PathName & FileList[Pos1+1 : Pos2] ADD(FileListQueue) BREAK END END END RETURN(ok) After the files are added to FileListQueue you can return a STRING from this procedure that will be the return string of the server side ClarioNET:GetFilesFromClient procedure. (3) Inspect return value and FileList Queue. When the ClarioNET:GetFIlesFromClient procedure returns the file transfer operation has been completed. Upon receipt of the files, the server applications QUEUE will contain the fully qualified file specification. In this example the ClarioNET:GetFilesFromClient procedure will receive ok as the return value. The server program must move or delete the file(s) as necessary and FREE the QUEUE. Note that after a normal session closedown the files on the server will be deleted. The files received are ALWAYS initially placed in the temporary work directory for the program instance, which is a subdirectory of the "Public" directory. Your server program must move and delete them as needed and FREE the QUEUE. It is not really required to delete them as they will be deleted from the temporary directory automatically when the session terminates, but is recommended as good housekeeping practice. *

Note! If one of the files was not able to be transferred to the client its name will be proceeded by 0: in FileListQueue.

40

How to Use Command Line

How to Use Command Line Parameters

The Client program can specify up to five values that the server program will receive as command line parameters. These variables are: CLRNT_C .Param1 CLRNT_C .Param2 CLRNT_C .Param3 CLRNT_C .Param4 CLRNT_C .Param5 STRING(200) STRING(200) STRING(200) STRING(200) STRING(200)

You can use the server EMBED location: ClarioNET:ClientParametersAvailableforInspection in the server application to check these parameters received from the client. *

These values will be available for inspection after the call to ClarioNETServer:Init.

41

Startup server information sent to client

Startup server information sent to client

The Server program can specify up to three (3) values that the server program can send to the client at program startup. These variables are. ClarioNET:Global.ServerString1 STRING(128) ClarioNET:Global.ServerString2 STRING(128) ClarioNET:Global.ServerString3 STRING(128) You can use the server EMBED location ClarioNET:SetServerStringsSentToClient to assign strings to these variables. * *

These values must be set prior to calling ClarioNETServer:Init. Note: These values will be available for inspection on the client after the call to ClarioNET:StartServerProgram on the client.

42

Calling Procedures in the Client

Calling Procedures in the Client

All the application logic in your server program executes on your server. Sometimes you may wish to take advantage of the CPU available on the client since it too has all the power to run complete Clarion Windows applications. While this takes you out of the thin client world, it certainly provides additional n-tier computing and distributed processing capabilities to you. ClarioNET makes it easy to implement this. You may create complementary functions and procedures between server and client, implementing code on the server to call a procedure on the client. This allows you to optionally use the processing power of the client. In short, you can include a procedure to do anything you want on the client system, and then call that procedure from the server. ClarioNET:ClientProcedure is a procedure you define in the client program that is called from the server using ClarioNET:CallClientProcedure. The parameters are passed directly to this procedure. Calling this procedure from the server enables you to access whatever functionality you desire to add on the client side. WinPtr is provided so you can access all the details of the window currently being used. This means you can do API calls.....hence, virtually any functionality can be added. Our intent was to use parameter P1 as a CASE parameter to decide what should be done. You can return up to 100 characters.
ClarioNET:ClientProcedure(*WINDOW WinPtr, STRING P1, <STRING P2>,.....,<STRING P15>)

WinPtr : Pointer to the currently OPEN window on the client. P1 -P15 : These are the same parameters passed to ClarioNET:CallClientProcedure. Note :If the server calls ClarioNET:CallClientProcedure then the ClarioNET:ClientProcedure (see below) will be called. The server will be waiting for a response from that procedure before servers normal ACCEPT processing continues. This procedure must be defined in your client program. It is defined as an EXTERNAL procedure in the ClarioNET client program library file. Returns : STRING Returns string os sent to the server and is the return value from ClarioNET:CallClientProcedure. On the server side you call: ClarioNET:CallClientProcedure PROCEDURE(STRING P1,<STRING P2>,<STRING P3>,<STRING P4>,<STRING P5>,<STRING P6>,<STRING P7>,<STRING P8>,<STRING P9>,<STRING P10>,<STRING P11>,<STRING P12>,<STRING P13>,<STRING P14>,<STRING P15>)

43

Calling Procedures in the Client

For example, you may place a button in the server application, and in the ACCEPTed event for the button embed code such as: ! Call Client Procedure P1" = PlayMovie ! Procedure name on client for passing parameter ReturnString = ClarioNET:CallClientProcedure(P1") On the client side ClarioNET:ClientProcedure MUST be defined....it is defined as an EXTERNAL procedure in the ClarioNET client library and must be found to finish linking the client EXE. The following code examines the P1 parameter and calls the function: !ClarioNET:ClientProcedure PROCEDURE(*WINDOW WinPtr, STRING P1, STRING P2, ......, STRING P15) !CODE WinHandle = WinPtr{PROP:HANDLE} IF P1 = PlayMovie IF NOT FileDialog(Select video file,AVIFileName,AVI Files |*.avi,0) RETURN(0) END PlayMovie(CLIP(AVIFileName)) ! PlayMovie is another user defined PROC END RETURN(Successful) The code above first examines the pointer to the window passed in the procedure and assigns it to a global variable, which the PlayMovie procedure will call later. It then takes care of other client side processing (a file dialog), which has to be done before calling the procedure. *

Note : The above PlayMovie procedure is a simple demo of using Clarion to display a file dialog and play a movie, and can be found at the SoftVelocity web site, in the Clarion FAQ section.

The full description of the client side procedure is as follows: ClarioNET:ClientProcedure PROCEDURE(*WINDOW WinPtr, STRING P1, <STRING P2>,......., <STRING P15>) The first parameter is a pointer to the currently open client window. Then the additional string parameters, of which only one P1 is necessary, are for passing whatever you wish the server to pass. Pass procedure names on the client for example. *

Note : We advise that when placing client procedures in your client programs that you use a single client with multiple client procedures for more than one customer. In other words, if you have, for example, a backup procedure for client As application, it may be inappropriate to leave that code in for client B, even though you dont expect to call it!

44 the

Placing a HyperLink in the Server

Placing a HyperLink in the Server Program

Hyperlinks (e.g., one click shortcuts such as http://, ftp://, mailto:) which may be automatically handled by the operating system on the client side are simply placed using the window formatter or by editing the window structure. The hyperlinks are easily implemented as attributes on a button, using MSG for the link and KEY for a special ClarioNET define. *

Note that they work in ClarioNET mode only! If you run the server .EXE file from a desktop, no link will be implemented.
MSG : This property will contain the command to be executed. The Windows API call ShellExecute is used on the client and passed this as the parameter. KEY : This property will contain a special ClarioNET EQUATE ClarioNET:WEBLINK. When the client is rendering the window and comes across this attribute it will trigger a different mode of handling an EVENT:Accepted for this button.

The following provides BUTTON structures for sample hypertext and email links: BUTTON(Open the ClarioNET Home Page...), | AT(198,50),USE(?Button25), FLAT, | FONT(Arial,9,,FONT:underline,CHARSET:ANSI), | MSG(http://www.clarionet.com), | KEY(ClarioNET:WEBLINK), | #ORIG(?Button25) BUTTON(Send E-Mail to ClarioNET Sales),AT(206,81), | USE(?Button26),FLAT, | FONT(Arial,9,,FONT:underline,CHARSET:ANSI), | MSG(mailto:sales@clarionet.com), | KEY(ClarioNET:WEBLINK), | #ORIG(?Button26)

45 How to Change a Client Side Cursor

How to Change a Client Side Cursor

Changing client side cursors are limited to the Clarion standard (STD) cursor equates. *

You cannot use .CUR files for use with ClarioNET.

When you wish to change the cursor place, the ClarioNET:SetCursor procedure call in some event in the server application. The following example embed code changes the client cursor to an hourglass: ClarioNET:SetCursor(CURSOR:Wait) Changing the cursor back to normal is as simple as: ClarioNET:SetCursor(CURSOR:None) Note that the cursor changes work in ClarioNET mode only! If you run the server .EXE file from a desktop, the cursor change will not work.

46

How to Display a Splash Screen

How to Display a Splash Screen at Startup

To incorporate a Splash screen or any code execution before the APPLICATION window is displayed in an ABC application use the following embed locations to execute the code: Local Objects/ABC Objects/WindowManager/Init/Code/AfterPrepareAlertKeys embed point. Window Events/OpenWindow *

Note! Standard ABC template generated Splash windows should work fine as is. ClarioNET was designed for them, including the timer used to close the window automatically.

In Legacy template generated code use the following as a guide to implement splash screens: Remove the Splash procedure specification that is normally entered on the Properties screen for the Main application Frame. In the EMBED location Accept Loop, Before CASE EVENT() handling, Priority(1), embed the code: IF EVENT() = EVENT:OpenWindow ClarioNET:OpenWindow(ClarioNETWindow) (YourSpashProcedure) END

47

Server Side Class Information

Server Side Class Information

Server Class Defined The ClarioNET:GlobalClass TYPE class is used to hold strings that can be passed between client and server. This class is instantiated in the clrnt5xs.dll file and needs to be defined as EXTERNAL,DLL(1) in your code. This class is defined in CLARIONET.INC. ClarioNET:GlobalClass CLASS STRING(200) Param1 STRING(200) Param2 STRING(200) Param3 STRING(200) Param4 STRING(200) Param5 STRING(128) ServerString1 STRING(128) ServerString2 STRING(128) ServerString3 STRING(200) ClientQueryRequestStrinn g DisplayClientEmptyReportMessage SHORT(1) END ClarioNET:Global ClarioNET:GlobalClass,EXTERNAL,DLL(1)

DisplayClientEmptyReportMessage : Set to 1 to enable automatic display of a message on the client when a report generated no WMF files. Set to 0 to disable it in cases where your template generated code displays its own message. This can me changed at ANY TIME during the program run.

48

Initialization and Closedown

Initialization and Closedown

The methods discussed in this section form the core procedure calls that provide the ClarioNET web deployment capability. They are to be placed in specific locations in relation to the opening, processing, and closing of windows and are all placed in relation to the ACCEPT loop code. *

Note ! You may not call these methods to force any behavior. They are designed as a set with many internal variables, flag, and data structures being used to coordinate the window processing tasks. The descriptions given below are for informational purposes only.
ClarioNETServer:Init( <STRING> PAC, LONG ServerNoActivityShutDown, LONG ClientNoActivityShutDown, USHORT DisplayServerScreen STRING BlowfishFlag) Product Activation Code ( PAC ) Specifies the License Password assigned to the licensed ClarioNET developer and turns off Demonstration mode. ServerNoActivityTimeOut : Sets the maximum number of minutes between activity received from client to keep the server based application running. If no client events are received for more than ServerNoActivityTimeOut minutes ClarioNET will issue a HALT(). This is the safeguard check to stop a running application that has lost contact with the client. Note : Server time out needs to be greater than the Client time out. If not it will be internally set to one minute longer than the Client time out. ClientNoActivityTimeOut : Sets the maximum number of minutes the client will wait for end-user keyboard or mouse interaction before signaling the server to close the application, and then the client itself will close. When this value is negative it signals continuous connection by the client. In this case the client simply contacts the server at this time interval to let the server know the session should not be dropped. DisplayServerScreen : When the EXE broker is used, setting this value non-zero provides display of the server application screen on the server when being run with ClarioNET. BlowFishFlag : This parameter is no longer used. ClarioNET ALWAYS uses 128 bit Blowfish encryption. ClarioNETServer:Init initializes the ClarioNET server component and must be the first ClarioNET function to be called. We recommend that it is the first procedure called in your program, if you are hand coding.

49 Initialization and Closedown

Initialization and Closedown

ClarioNETServer:Init performs all the initialization of the ClarioNET server side system. If certain command line parameters are not found then the program is assumed to be launched locally and all further ClarioNET calls are disabled. This function returns a zero (0) in all cases except when a Query was sent from a client program using the ClarioNET:QueryServerProgram procedure call. In this case you must respond to the query with the ClarioNETServer:SendClientQueryResponse procedure. ClarioNETServer:Kill This disconnects the application from the Clarion Application Broker, disposes of created data, and performs final housecleaning. This must be called to deallocate memory when ClarioNETServer:INIT was called and a successful ClarioNET session was started. ClarioNETServer:Active This is used to determine if the ClarioNET server system is active. Returns 1 for active, 0 for inactive. ClarioNETServer:Pause ClarioNETServer:Resume When your server application will perform a task that may not be complete before the clients HTTP connection timeout (specified by CLRNT_C.ConnectionTimeout) -or-the server or client no activity period will be exceeded, there is a danger of the system shutting itself down. These two procedure calls pause and resume the checking of the timeout values. Your server and client will wait an unlimited amount of time when ClarioNETServer:Pause is called. *

Note! Use these carefully. Use them only when starting a long process or report printing phase. BE SURE TO CALL ClarioNET:ServerResume.

50

Client Queries : A Hidden Jewel

Client Queries : A Hidden Jewel

A ClarioNET client has the ability to call a server procedure immediately upon connection. On the client side, before any other calls to start a server program, the ClarioNET:QueryServerProgram procedure can send a single STRING to the server in order to get a fast response of some specific information. ClarioNET:QueryServerProgram can be called as many times as you wish BUT ONLY BEFORE THE SESSION STARTS. *

Note! On the server side VERY LITTLE initialization is done and so you can build special procedures into the server program to handle queries very, very quickly.

On your server program, the ClarioNET template always adds the following startup code: IF ClarioNETServer:Init(., 20*60, 15*60, 0,1) ClarioNETServer :SendClientQueryResponse(ClarioNET:HandleClientQuery() ) RETURN END When ClarioNETServer:Init is called the procedure examines the way in which the program was launched. If it was launched with a Query from a client it returns a non-zero value. In this case your server code must respond back to the client using the ClarioNET:SendClientQueryResponse procedure. In addition the program must exit immediately. In the example source code shown above, the template automatically adds the ClarioNET:HandleClientQuery call, prototype, and procedure to your application source code. The ClarioNET:HandleClientQuery procedure is a placeholder where YOU need to add code to inspect the query string sent from the client which is contained in ClarioNET:Global.ClientQueryRequest. When finished you can return a string from this procedure to return to the client. On the client side you can call ClarioNET:QueryServerProgram(STRING),STRING,PROC BEFORE the procedures to launch a program session. This method call allows you to send a message to the server program and have specific tasks performed. Use this function only before starting a client session. *

This one client procedure and the corresponding response code on the server can give you tremendous power....almost to the point of offering complete web server capabilities.

51

Client Queries : A Hidden Jewel

This is useful, for example, to get a list of the available programs the client can connect to. For example: DelimitedProgramList STRING(200)

DelimitedProgramList = ClarioNET:QueryServerProgram(getprogramlist) On the server the ClarioNETServer:Init procedure returns a one (1) when a query has been received. This allows you to call specific procedures in the server program to respond to the query by examining the passed string parameter. In the case of this example you could read a database of the ClarioNET server programs available and send back that information as a delimited string such as: INVOICE.EXE:PAYABLES.EXE:RECEIVABLES.EXE The ClarioNET:QueryServerProgram procedure would then return this string to the DelimitedProgramList STRING and from there your client program could parse the information (looking for a : ), assign it to a drop combo, and let the user select which program to launch on the server.

52

PushWindow : Forced Client

PushWindow : Forced Client Window Display

The PushWindow set of procedures give you the ability to forcefully display a window on the client, update the displayed information, and close it down. You may only call these procedures when the server program has been notified of a client action (button press, menu selection, entry change, etc). *

Note: The Push Window system is a separate code area in the client and will not respond to ANY control messages from the server EXCEPT ClarioNET:UpdatePushWindow and ClarioNET:ClosePushWindow. Therefore, you must NOT call any procedures, open windows, read INI files, or anything elseor the system will hang.

This PushWindow system was designed for you to display continuously changing status screens when a long process is being performed. The window that you define is only opened briefly.... long enough to read the layout and get the USE variable contents. You cannot write to the Push Window screen because it is not open. If you OPEN it yourself the ClarioNET code will try opening it again and the program will GPF. Simply define a window and specify static USE variables for any controls that will be changed as part of your updating process. These procedures take a Clarion WINDOW structure as the parameter. Any data that will change on this window MUST be assigned to a static USE variable. The PushWindow procedures work as follows: Calling ClarioNET:OpenPushWindow(YourWindow) causes YourWindow to be opened, scanned, closed, and the client then sent a data structure and instructions to draw the window. The client then responds to the server and waits for either a UpdatePushWindow or ClosePushWindow call. On the server you can proceed to perform programming tasks, most likely some kind of process. During this process you can change the values in the USE for the controls in YourWindow and call ClarioNET:UpdatePushWindow. Calling ClarioNET:UpdatePushWindow causes YourWindow to be opened, scanned, closed, the screen compared to the previous, and only the changes sent to the client. The client then responds to the server and again waits for either a ClarioNET:UpdatePushWindow or ClarioNET:ClosePushWindow. Using this design never leaves YourWindow open but provides a display framework for quick scan and send. No user interaction can occur on the client. The window is simply displayed and does not respond as the client waits for the next instruction from the server. *

Do not call any other ClarioNET procedures between the OPEN Note: and CLOSE calls except the PushWindows UPDATE procedure.

The following provides the PushWindow declarations:

53

PushWindow : Forced Client Window Display

ClarioNET:OpenPushWindow (Window) Window : A Clarion WINDOW structure. This procedure displays the Window on the client. ClarioNET:UpdatePushWindow(Window) Window : A Clarion WINDOW structure. This procedure updates Window on the client with and changes to the Window control USE variables. ClarioNET:ClosePushWindow(Window) Window A Clarion WINDOW structure. This procedure updates Window on the client with and changes to the Window control USE variables.

PushWindow Example....
The following ROUTINE will cause a small window to appear on the client and the progress bar to advance in 5% steps with each LOOP cycle. When the LOOP is complete the window will be cleared on the client and the client will again await further instructions. SomeProcess ROUTINE DATA Progress1 LONG SHORT I window WINDOW,AT(,,216,38),GRAY,DOUBLE STRING('Process Completion Status...'),AT(11,8) PROGRESS,USE(Progress1), AT(17,22,190,5),RANGE(0,100) END CODE Progress1 = 0 ClarioNET:OpenPushWindow(window) LOOP I=1 TO 100 BY 5 <Process Logic> Progress1 = I ClarioNET:UpdatePushWindow(window) END ClarioNET:ClosePushWindow(window)

54

Window Management

Window Management
The Window Management procedures provide initialization, maintenance, and closing of the client window. These methods must be used in each procedure that provides WINDOW display processing. *

Note! These procedures work as a coordinated set and SHOULD NOT be called thinking that you can force some manner of functionality.

ClarioNET:OpenWindowInit( ClarioNETWindowClass CW) This must be called after OPENing the window and before ClarioNET:InitWindow. This function is called at the beginning of each procedure and is used by the ClarioNET system to detect if the current procedure was called from EVENT:OpenWindow in the calling procedure. This is important to determine how to continue when returning to the calling procedure. CW : An instance of the ClarioNETWindowClass for this procedure.

ClarioNET:InitWindow( ClarioNETWindowClass CW, *Window ThisWindow, SHORT WindowType, <LONG DisplayTime> ) This function registers the window with the ClarioNET system. It should be called after the window is OPEN()ed and before the ACCEPT loop. CW : An instance of the ClarioNETWindowClass for this procedure. ThisWindow : The label of the WINDOW structure that will be used for the ACCEPT loop. Type : A window type number; 1 =WINDOW, 3 = APPLICATION DisplayTime : The display time in seconds for the window. A non-zero number indicates the window on the client will close automatically. This results in an EVENT:CloseWindow being posted to the ACCEPT loop. This is used primarily for Splash windows that need to close automatically.

ClarioNET:OpenWindow( ClarioNETWindowClass CW) This function is called during the EVENT:OpenWindow event. It causes some housekeeping and status monitoring to be performed. CW : An instance of the ClarioNETWindowClass for this procedure.

55

Window Management

ClarioNET:TakeEvent( ClarioNETWindowClass CW) CW : An instance of the ClarioNETWindowClass for this procedure. Returns : A non-zero return value indicates the Window should be closed by POST(Event:CloseWIndow). ClarioNET:TakeEvent is the most important ClarioNET function. It must be called as the first item in the ACCEPT loop. It performs the following actions: On return from this function, if there has been client activity, the affected controls USE variable is updated, keycode PRESSed, and the EVENT Posted to the ACCEPT loop. Your code can continue as usual without knowing that the data entry and/or event had not occurred on the local machine. After your code has performed all its tasks and the window has been modified as needed and is ready for display, this procedure will scan the window and send the changes to the client. ClarioNET:CloseWindow( ClarioNETWindowClass CW) CW : An instance of the ClarioNETWindowClass for this procedure. This procedure MUST BE CALLED on EVENT:CloseWindow in ALL ACCEPT LOOPS. This procedure does not forcefully close the client window; it simply sets internal variables to prepare for the ClarioNET:KillWindow call that contacts the client as needed. ClarioNET:KillWindow( ClarioNETWindowClass CW) CW : An instance of the ClarioNETWindowClass for this procedure. This function is used to finish up window processing after the CLOSE(Window) call is executed. *

Note ! This procedure call should be the last code to execute before returning from the procedure.

ClarioNET:RegisterBrowse( ClarioNETWindowClass CW,BrowseClass BRW) CW : An instance of the ClarioNETWindowClass needs to be defined in the DATA area for the WINDOW being used. BRW : An instance of the BROWSE class that has been instantiated in the module to handle all browse activities for the LIST control in the window. This procedure is only used in ABC template generated programs to support toolbars.

56

Miscellaneous Procedures

Miscellaneous Procedures
The following procedures are also available for use by programmers: ClarioNET:ClientBeep(SHORT Sound) Sound A standard Clarion sound defined using a BEEP: equate. This function creates a BEEP tone on the clients computer. ClarioNET:SetUpdateExtents This procedure is used to set the extent to which ClarioNET scans the window and its controls for changes at runtime. See the appendices for further details. ClarioNET:GetTempDir, STRING Returns the full drive and directory specification for the temporary directory being used for the unique server program execution instance. *

If you place files here you need to REMOVE them when exiting the Note: program .

ClarioNET:GetClientIPAddress, STRING This returns the connecting client program's IP address in dotted-decimal form, i.e. "208.123.45.121" ClarioNET:AbortCloseWindow(ClarioNETWindow) This can be used immediately before ClarioNET:CloseWindow to prevent a window from being closed. This prcedure call must be IMMEDIATELY followed by a "CYCLE" statement. ClarioNET:GetINI( Section1, Entry, <Default>, <Filename>) ClarioNET:PutINI( Section1, Entry, <Default>, <Filename>) ClarioNET allows setting and retrieving of INI file values on the client or server. There are five procedure calls that you can use (two of them being the standard GETINI and PUTINI Clarion procedures). These two procedures always reference the client INI files. The parameters and return values for these functions are identical to the Clarion GETINI and PUTINI procedure. These two methods should only be called: After the call to ClarioNETServer:Init and before ClarioNET:OpenWindow. AFTER the main window has closed.

57

Miscellaneous Procedures

Any other time when the server is responding to an event sent from the client.

The Client must be waiting for a response from the server when you call these procedures. ClarioNET:INIMode( SHORT Mode), SHORT Mode : Specifies the mode used in the standard Clarion GetINI and PutINI functions. A 1 directs all standard Clarion GETINI and PUTINI calls to the remote client computer. A 0 directs all GETINI and PUTINI calls to the server. This function returns the last INIMode used. ClarioNET redefines a number of standard Clarion procedures to its own internal ones. The standard Clarion GETINI and PUTINI procedures have been redefined to trap all INI file activity and the redirect it to either the server or client computer. *

Note: Enabling all GETINI and PUTINI to be directed to the client may have performance penalties. In a web deployment each call requires a roundtrip communication which may lessen the perceived speed of your client.

ClarioNET:SetWindowPos(SHORT HScrollPos = -1, SHORT YScrollPos = -1) This allows you to set the position of the currently open window's scroll bars. When ClarioNET is NOT active this merely issues 0{PROP:VScrollPos} = VScrollPos and 0{PROP:HScrollPos} = HScrollPos. ClarioNET:ClientEventCOntrol(SIGNED FEQ, SHORT Flag, SIGNED Event) This allows you to restrict the eventa that the client sends back to the server for a particular control. FEQ : Field Equate Label of the control to be modified Flag : 1 = Send event, 0 = Disable event. Event : Clarion "EVENT:..." equate for the event send status to modify

58

RunCallClass

RunCallClass
RunCallClass ProgramName Parameter Frequency RunCall CLASS,TYPE CSTRING(512) CSTRING(512) LONG END RunCallClass,EXTERNAL,DLL(1)

RunCall is defined in the ClarioNET server extension DLL. This class allows you to specify an EXE program file to run at Frequency second intervals during the execution of the server application. The Clarion RUN command is used with NoWaitFlag. The parameter is sent as the command line parameter.

59

Client Application Class

Client Application Class

This section will be of greatest interest to those who wish to create a ClarioNET client from scratch. ClarioNETSession CLASS

A CLASS named CLRNT_C of type ClarioNETSession is defined in the clrnt50c.lib and clrnt55c.lib files. You must reference this class in the main program portion of your client program as: CLRNT_C ClarioNETSession, EXTERNAL This class provides the properties (variables) that you define to connect to the server application and is defined in CLIENT.INC.
ClarioNetSession HostProgramName HostProgramDirectory ServerName ServerPort UserAgent UseProxy UsePreconfig ProxyServer ProxyUserName ProxyPassword GraphicDownloadFlag ConnectionTimeout CharSet ProgressUpdateFrequency PingFlag LaunchingWindow UseLaunchingWindow NoticeWindowColor ClientTempDirectory Param1 Param2 Param3 Param4 Param5 HostSessionID ServerString1 ServerString2 ServerString3 EventSelectedAllowed DefaultCursor FileTransferProgressDisplay StatusIcon_Comm StatusIcon_Working StatusIcon_OK ServerProcessID EnableESCKey BrokerProcessID CLASS,TYPE CSTRING(128) CSTRING(128) CSTRING(128) UNSIGNED(80) CSTRING(50) SHORT SHORT CSTRING(256) CSTRING(128) CSTRING(128) UNSIGNED UNSIGNED SHORT SHORT SHORT &WINDOW SHORT LONG CSTRING(512) STRING(200) STRING(200) STRING(200) STRING(200) STRING(200) CSTRING(128) STRING(128) STRING(128) STRING(128) SHORT STRING(100) SHORT CSTRING(128) CSTRING(128) CSTRING(128) LONG SHORT(0) LONG

60

Client Application Class

ClientIPAddress STRING(20) END

Class Properties
HostProgramName : The HostProgramName property is a CSTRING(128) that holds the program name to execute on the server. For example, INVOICE.EXE. Be sure to add the EXE extension. HostProgramDirectory : Holds the virtual directory path on the server where the program is located. For EXE broker this is exec/yourappdir. ServerName : This is the proper Internet address of the application server. The fully qualified name can be either an IP address or a domain name, i.e.www.clarionet.com or 216.237.145.63. Note : When testing with the EXE broker on the same machine you might be using localhost as the server name. Be sure to test this with a browser to make sure the Clarion Application Broker can be reached. ServerPort : Holds the server port. Default is port 80. Next most common HTTP port is 8080. UserAgent : This identifies the client to the server and is set to Clarionet when not assigned a string in the client startup program. UseProxy : Set this to 1 to enable use of data that specifies a proxy server. UsePreconfig : Instructs client HTTP communications system to retrieve proxy server settings from the Windows registry. Internally this uses INTERNET_OPEN_TYPE_PRECONFIG as the dwAccessType parameter for a call to wininet function InternetOpen. ProxyServer : Allows you to specify the proxy server. Setting UsePreconfig to 1 will ignore this value. ProxyUserName : Holds the user name for client proxy authentication. ProxyPassword : Holds the password for client proxy authentication. GraphicDownloadFlag : In a thin client design you probably want as few files on the client as possible, and those files do not need to be persistent between client working sessions. In most programs there are many little graphic items used as icons and images in the form of ICO, GIF, JPG, WMF, and other format files. ClarioNET transfers these files, as specified in your server program, to the client during the worksession. However, you may wish to cache these files so that they only need to be downloaded once or download them every time they occur in a new window, and you need to decide whether they should be erased after every session or be left on the hard disk to be used next time.

61

Client Application Class

GraphicDownloadFlag allows you specify which will be the best for your application. We use a two-digit number to specify the method. The lower digit instructs when to get the file from the server, and the upper digit is a flag that instructs ClarioNET to erase the files when the client session has finished. Flag values that do not erase after the session: 1 Always download the file with every new window or window update. 2 Download the file once each session, even if it already exists on the disk, and use it for all future occurrences of the same file name. 3 Download the file regardless if it exists and use it for all future occurrences of the same file name. Adding ten (10) to these values causes the download files to be erased after the client session ends. ConnectionTimeout : Specifies the time in seconds that the HTTP function waits for a response from the server before returning and posting a No response from server message. We advise setting this to a high value, perhaps 30, until such a time as your typical server response time is known. 10 seconds would be typical. CharSet : Specifies the default character set to use for the Client when none is specified from the server. This value is a Clarion CHARSET: equate from the EQUATES.CLW file. Typically CHARSET:ANSI would be used , but if in doubt, do not assign any value. If none specified the value is zero, which equates to CHARSET:ANSI. The availability of this setting can help non-English clients display the characters correctly. ProgressUpdateFrequency : When a PROGRESS control is placed on a window this indicates that the server program might be performing processing that will update the window contents. When a PROGRESS control is used on a window the client will automatically contact the server every ProgressUpdateFrequency/100 seconds and request a refresh of its status. Depending on your program, the window will be updated, closed, or a newly opened window will appear. It is recommended to set this value to double the average client/server/client communication time. The default value is three seconds, however, we recommend smaller time intervals for faster TCP/IP connections. PingFlag : If this flag is set to 1 before the client procedure call ClarioNET:StartServerProgram, the server programs simply returns the date and time on the server and version of the ClarioNET server DLL. This can be used to test the existence of the program in a quiet way. LaunchingWindow & UseLaunchingWindow : When the two procedures to launch the server program are called there is usually a wait time where the client window will disappear. These two properties allow you to design a window that will be displayed

62

Client Application Class

during this period. Although the display may be rather brief, if the Internet connection is slow this will fill the time with at least some indication of activity. LaunchingWindow should be assigned a WINDOW name using the &= operator. UseLaunchingWindow should be set to 1 to instruct ClarioNET to actually display the window. NoticeWindowColor : Used to assign a background color to the internal ClarioNET notification windows. Default is 0696934H. ClientTempDirectory : A temporary directory where ClarioNET can store swap files, icons, images, and print files. If unassigned ClarioNET will get the Windows temporary path from the Windows API. Param1 Param2 Param3 Param4 Param5 : These are command line parameters that you can specify, which will be passed to the server based application when the ClarioNET:StartServer procedure is called. *

Note :The server receives all five parameters. If unassigned they will be sent as zero length strings.

The Following values are available AFTER calling ClarioNET:StartServerProgram: HostSessionID : This is the session ID of the instance of the server program. It is used by ClarioNET to identify which session of your server program is linked to the current client session. Note : HostSessionID is assigned by the server-based program. ServerString1 ServerString2 ServerString3 : Three strings received from the server when the application is launched, that is after ClarioNET:StartServer returns. See index for separate section describing usage. Note: ServerString1 and ServerString3 will be blank when running in demonstration mode. EventSelectedAllowed : Normally EVENT:Selected is not sent from the client to the server. The main reason is that EVENT:Selected is usually always followed by EVENT:Accepted and sending both creates two Client/Server/Client communications. This would double the perceived response time for each change. If EVENT:Selected is not sent then there is no lag time as users often click controls for no real reason.

63

Client Application Class

However, there will be times when your program code needs to trigger on EVENT:Selected. There are two ways you can change this property: 1. At client startup set this property accordingly. 2. Use ClarioNET:CallClientProcedure with a flag set so that your client side logic is triggered to set this value. DefaultCursor : Set this value before starting the client session with the CURSOR name to use as the default cursor. This name MUST MATCH the name given when linking in the cursor as a resource if a disk baked CUR file is used. FileTransferProgressDisplay : This is set when a file transfer operation is started on the server. A non-zero number indicates that the internal file transfer progress window should be displayed while files are being transferred. You can set this to zero on the client side when sending files to the server if you wish to change the behavior. StatusIcon_Comm StatusIcon_Working StatusIcon_OK : Enables you to set the ICONs displayed in the client title bar to indicate ClarioNET comminucation status. StatusIcon_Comm : Displayedwhile client is sending/receiving information. StatusIcon_Working : Displayed when received information is being processed. StatusIcon_OK : No communication is taking place. ServerProcessID : This is the "ProcessID" of the program instance running on the server that this client session is tied to. THis value is available immediately after the call to ClarioNET:StartServerProgram() returns.

64

ClarioNET Client Startup

ClarioNET Client Startup Procedures

ClarioNET:StartServerProgram Only two procedures are needed by the ClarioNET client library to implement the entire ClarioNET client system. ClarioNET:StartServerProgram is the first procedure, takes no parameters, and returns 0 if completed without problems. A non-zero return value indicates a problem occurred. If ClarioNET:StartServerProgram returns zero (0) then the server program has been started and the values for ClarioNET:Global. ServerString1, ClarioNET:Global. ServerString2, and ClarioNET:Global.ServerString3 have been received from the server. The next step is to hide your launching program screen and hand control over to the ClarioNET client system. After this is done your client program will have no interaction with the system (except if the client side file transfer procedures of Call Client procedure functinalities are used). In our demo programs we simply use HIDE(0) to hide the current screen. Do not call this procedure with START(). Returns : SHORT. The following EQUATES are specified in the client.inc file can be used to test the return value from ClarioNET:StartSession: CLRNT_ERR_NONE CLRNT_ERR_NO_CREATE_TEMP CLRNT_ERR_HTTP_FAILURE CLRNT_ERR_SESSION_FAILURE CLRNT_ERR_DECOMP_INIT_FAILURE CLRNT_ERR_NO_HOSTNAME CLRNT_ERR_NO_HOSTDIR CLRNT_ERR_NO_SERVERMAME CLRNT_ERR_VERSION_MISMATCH ClarioNET:StartClientSession This procedure begins the remote client session and will handle the entire communication and user interface display process. It will not return until you have exited the program or a Client Time Out forced automatic closing of the application. This should only be called after a successful return from ClarioNET:StartServerProgram. Returns : SHORT. The following can be returned from ClarioNET:StartClientSession: CLRNT_ERR_NONE CLRNT_ERR_INACTIVE CLRNT_ERR_HTTP_TIMEOUT HTTP CLRNT_ERR_PING No errors Client was inactive and closed automatically System timed out PingFlag is set No errors Client was Inactive and closed automatically System timed out Could not start session,server problem Could not initialize decompression library No HostProgramName was specified No HostProgramDirectory was specified No ServerName was specified Client/Server Version Mismatch

65

How ClarioNET Manages Window Properties

How ClarioNET Manages Window Properties

ClarioNET performs the work of duplicating the user interface to a Clarion program on a remote client by inspecting the attributes (or properties) of the window and its component controls. There are three significant times when ClarioNET must insure that the client and server windows and controls are synchronized When building a client window When a server program window is first being displayed, your Clarion code takes whatever steps are required to prepare the window for display, then the ClarioNET code takes over. This happens when ClarioNET:TakeEvent is called and there are no pending EVENTS in the ACCEPT loop. At this time the window is ready for display and ClarioNET scans the entire WINDOW or APPLICATION structure and extracts information to build the remote window. When a user action on the client has changed a control or window property This most commonly occurs when an event occurs on the client to change a data entry, press a button, select a radio or checkbox, or a list/combo box item is selected. The client system detects the changes and sends them to the server-based programs ClarioNET extension code. ClarioNET then replicates the users action within the server program and the ACCEPT loop logic can process the user actions. The accept loop sees an event or keypress just as if it happened locally. When the server based program has made changes to the window or its controls After the server based program receives the changes from the client it continues to execute your program code just as if a local user had made the change. The program code does whatever it is designed to do and updates the screen control USE variables or makes changes to icons, images, or the properties of the window or its controls. After screen updating is finished and the internal Clarion ACCEPT processing sees that no additional events are waiting to be processed (i.e. the window is ready for redisplay), ClarioNET sends just the changes to the client.

66

WINDOW Complexity

WINDOW Complexity Limitations

Although ClarioNET has enormous capacity to replicate a Clarion user interface there are some limitations that apply. Within the items below the word total means that for the sum of all the type of controls listed the quantity cant exceed the maximum given. However, this is per window and so you can see that the windows can be tremendously complex before the limits are exceeded. Maximum of 40 total LIST and COMBO controls per window. Maximum of 200 fields in a LIST QUEUE. Maximum of 1000 total ENTRY, SPIN, CHECK, SHEET, OPTION, PROGRESS, ITEM, LIST and COMBO controls per WINDOW. Maximum of 25 TEXT controls per window. Maximum of 40 ICONs within each LIST control. Maximum of 25 ALRT keys per window and per control. No aggregate limit.

67

WINDOW Properties Supported

WINDOW Properties Supported

Attribute ALRT* AT AUTO CENTER CENTERED COLOR CURSOR DOCK DOCKED DOUBLE DROPID FILLCOLOR FONT FONTCHARSET FONTCOLOR FONTNAME FONTSIZE FONTSTYLE GRAY HEIGHT HLP HSCROLL HSCROLLPOS MAXIMIZE MAXWIDTH MDI MINHEIGHT MINWIDTH MODAL MSG NOFRAME NOTIPS PALETTE PIXELS RESIZE SELECTEDCOLOR SELECTEDFILLCOLOR SNAPHEIGHT SNAPWIDTH STATUS** SYSTEM TEXT*** TILED TIMER TOOLBOX Supported Y Y Y Y Y Y N N N N N Y Y Y Y Y Y Y Y Y Y Y Y Y Y N Y Y N Y N Y Y Y Y Y Y Y Y Y Y Y Y N N OK Modify at Runtime N Y N N Y Y N N N N N N Y Y Y Y Y Y N Y Y N Y N N N N N N Y N Y N Y N N N N N Y N Y Y N N

68

WINDOW Properties Supported

VSCROLL Y N

*First 25 AlertKeys returned by {PROP:Alrt, x}, except MouseLeft **Zones 1 to 4 only. *

Note: If a WINDOW or APPLICATION has a RESIZE and NOFRAME and there is no text then it will appear without a title bar

The following events in the client side ClarioNET program are sent to the server. EVENT:Accepted EVENT:ScrollUp EVENT:PageDown EVENT:Locate EVENT:MouseOut EVENT:Expanding EVENT:Selected ( only when EVENT:AlertKey EVENT:ScrollDown EVENT:ScrollTop EVENT:ScrollDrag EVENT:Expanded EVENT:Contracting flag in client is set) EVENT:NewSelection EVENT:PageUp EVENT:ScrollBottom EVENT:MouseIn EVENT:Contracted EVENT:Sized

69

Controls Property Support

Controls Property Support

The following tables indicate the supported attributes (properties) for each Clarion control supported by ClarioNET. This is indicated in the Supported column. The Modify at Runtime column indicates if the attribute is allowed to be modified with property syntax code (i.e. ?Item{PROP:XPos} = 12 ) at runtime. A value of 1 or 2 indicates the extent level for the attribute value to be sent to the server (see ClarioNET:SetUpdateExtents). A N in this column indicates the attribute is not scanned for changes throughout the lifetime of the procedure.

BOX
Attribute AT COLOR DISABLE HIDE LINEWIDTH ROUND FILL FULL SCROLL Supported Y Y Y Y Y Y Y Y Y OK Modify at Runtime 2 2 1,2 1,2 2 2 2 2 2

The BOX control does not generate any events, therefore no update to the server will occur.

BUTTON
Attribute ALRT AT COLOR CURSOR DEFAULT DELAY DISABLE DROPID FLAT FONT FILLCOLOR FULL HIDE HLP ICON Supported Y Y Y N Y N Y N Y Y Y Y Y Y Y OK Modify at Runtime N 2 1,2 N 1,2 N 1,2 N 2 2 2 2 1,2 Y Y

70

Controls Property Support

IMM KEY LEFT MSG REPEAT REQ RIGHT SKIP SCROLL STD TEXT TOOLTIP TRN N Y Y Y N Y Y Y Y Y Y Y Y N N N 2 N N N 2 N N 2 2

The BUTTON control generates the following events which cause updates to the control on the server: EVENT:Accepted EVENT:AlertKey Also see How to Place a Hyperlink in the Server Program for additional BUTTON capabilities.

CHECK
Attribute ALRT AT COLOR CONTENTS CURSOR DISABLE FALSEVALUE FLAT FONT FULL HIDE HLP ICON KEY LEFT MSG REPEAT REQ RIGHT SCROLL SKIP TEXT TOOLTIP TRN Supported Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y N Y Y Y Y Y Y Y OK Modify at Runtime N 2 2 1,2 N 1,2 2 2 2 2 1 Y 2 N 2 2 N N N N 2 2 2 2

71

Controls Property Support

2 N

TRUEVALUE VALUE

Y Y

The CHECK control generates the following events which triggers sending update information to the server: EVENT:Accepted EVENT:AlertKey EVENT:Selected ( When client EventSelectedAllowed variable is set = 1 ) The true and false values of the CHECK, KEYCODE, and EVENT are also sent to the server.

COMBO
COMBO controls have the following constraints:

Anything that can be specified as a FORMAT that controls the COMBO

appearance is supported.

Up to 200 QUEUE fields are recognized. This includes the invisible extra
queue fields used for formatting.

Scroll bars and VCRs jump to a record on a keystroke and double mouse
click.

Trees, including the expand and contract icons are supported. Up to 30 ICONs in the list tree is supported. Up to 40 total LIST and COMBO controls are supported per
WINDOW. Attribute ALWAYSDROP ALRT AT CAP CENTER COLOR COLUMN CONTENTS CURSOR DECIMAL DISABLE DRAGID DROP FONT FORMAT Supported Y Y Y N Y Y Y Y Y Y Y N Y Y Y OK Modify at Runtime N N 2 N 2 2 2 N 2 1 N 2 2 2

72

Controls Property Support FROM FULL GRID HELP HIDE HSCROLL ICONLIST IMM INS KEY LEFT LINEHEIGHT MARK MASK MSG NOBAR OVR REQ READONLY RIGHT SCROLL SKIP TEXT TOOLTIP TRN UPR USE,3 USE,4 VCR VSCROLL VSCROLLPOS Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y N 2 2 2 1 1 Y N N N 2 2 2 N 2 2 N N N 2 N 2 N 2 2 N N N 2 1 1

The COMBO control generates the following events which triggers sending update information to the server: EVENT:AlertKey EVENT:Expanded EVENT:Contracted The values of the following properties are sent to the server: PROPLIST:MouseDownRow PROPLIST:MouseDownZone PROPLIST:MouseDownField PROPLIST:MouseUpRow PROPLIST:MouseUpZone PROPLIST:MouseUpField EVENT:ScrollDrag The value of PROP:VScrollPos is sent to the server.

73

Controls Property Support

EVENT:Selected The value of PROPLIST:MouseDownRow is sent to the server. EVENT:NewSelection The values of PROPLIST:MouseDownRow and PROPLIST:MouseDownZoneare set for the next property inspection. EVENT:Accepted EVENT:Contracting EVENT:Expanding EVENT:Locate EVENT:PageDown EVENT:PageUp EVENT:PreAlertKey EVENT:ScrollBottom EVENT:ScrollDown EVENT:ScrollTop EVENT:ScrollUp

ELLIPSE

Attribute AT COLOR DISABLE FILL FULL HIDE LINEWIDTH SCROLL

Supported Y Y Y Y Y Y Y Y

OK Modify at Runtime 2 2 1,2 2 2 1,2 2 2

The ELLIPSE control does not generate any events, therefore no update to the server will occur.

ENTRY
Attribute ALRT AT CAP CENTER COLOR CURSOR 74 Supported Y Y Y Y Y Y OK Modify at Runtime N 2 2 2 2 N

Controls Property Support DECIMAL DISABLE DEFAULT DROPID FILL FLAT FONT FULL HIDE HLP IMM INS INTOOBAR KEY LEFT MASK MSG OVR PASSWORD READONLY REQ RIGHT SCROLL SKIP STD TOOLTIP TRN UPR Y Y Y N Y Y Y Y Y Y Y Y N Y Y Y Y Y Y Y Y Y Y Y N Y Y Y N 1,2 N 2 2 2 2 1,2 Y N

2 2

2 N 2 2 2

The ENTRY control generates the following events which triggers sending update information to the server: EVENT:Accepted EVENT:AlertKey EVENT:Selected (only when client side property "EventSelectedAllowed" is set to "1") EVENT:NewSelection, (only if IMM is set) After one of these events the CONTENTS of the control, the EVENT, and KEYCODE are sent to the server. For all EVENTs, the contents of the server ENTRY controls USE variable is changed, the EVENT is posted, and PROP:Touched is set to TRUE. If EVENT:NewSelection and EVENT:AlertKey is the EVENT then PRESSKEY(Keycode) is used to insert the keycode. The server program can examine KEYCODE or EVENT to retrieve the values sent from the client.

75

Controls Property Support

GROUP
Attribute ALRT AT BEVEL BOXED CENTERED COLOR CURSOR DISABLE FONT FULL HIDE HLP MSG SKIP SCROLL TEXT TOOLTIP TRN Supported Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y OK Modify at Runtime N 2

2 1,2 2 1,2

The GROUP control does not generate any events, therefore no update to the server will occur.

IMAGE
IMAGE controls have the following constraints: Image controls can have an image specified at compile time or runtime. Image controls are unique in that the image contents must be extracted and written to a file at runtime. This file is then transferred to the client and assigned to the image control. PROP:TempImagePath and PROP:TempImage properties are used to control the location and name of the temporarily extracted image. If the image is assigned at runtime, the image file must be located in the executables directory or in the PATH. Attribute AT DISABLE FULL Supported Y Y Y OK Modify at Runtime 2 1,2 2

76

Controls Property Support HIDE SCROLL CENTER TILED HSCROLL VSCROLL Note: file. Y Y Y Y Y Y 1,2

At runtime, ClarioNET uses PROP:TempImage to extract the image to a

The IMAGE control does not generate any events, therefore no update to the server will occur.

ITEM
Attribute AT CHECK COLOR CONTENTS DISABLE FIRST FONT HIDE HLP ICON KEY LAST MSG SEPERATOR STD TEXT Supported Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y OK Modify at Runtime N

When an ITEM is selected, EVENT:Accepted is posted to the server program.

LINE
Attribute Supported OK Modify at Runtime

The LINE control does not generate any events, therefore no update to the server will occur. AT COLOR DISABLE FULL HIDE Y Y Y Y Y

77

Controls Property Support

LINEWIDTH SCROLL

Y Y

LIST
A LIST control is treated the same as a COMBO control. For information on the LIST control refer to the COMBO Control section.

MENU
Attribute AT COLOR DISABLE FIRST FONT HIDE HLP ICON KEY LAST MSG SEPERATOR RIGHT STD TEXT Supported Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y OK Modify at Runtime N N 1 N N 1 Y 2 N N 2 N N N 2

When a menu item is selected, EVENT:Accepted is posted to the server program.

OPTION
Attribute ALRT AT BEVEL BOXED COLOR CONTENTS CURSOR DISABLE FONT FULL HIDE HLP KEY Supported Y Y Y Y Y Y N Y Y Y Y Y Y OK Modify at Runtime N 2 2 2 2 1,2 N 1,2 2 2 1,2 Y N

78

Controls Property Support MSG SCROLL SKIP TEXT TOOLTIP TRN Y Y Y Y Y Y 2 2 2 2 2 2

The OPTION control generates the following events which trigger update information to the server: EVENT:Accepted EVENT:AlertKey EVENT:Selected, (client property EventSelectedAllowed is set to 1) After one of the above events occur, the CHOICE of the control, the EVENT, and KEYCODE are sent to the server. The new RADIO control is selected on the server and the OPTION control report it using CHOICE.

PANEL
Attribute AT BEVEL DISABLE FILL FULL HIDE SCROLL TRN Supported Y Y Y Y Y Y Y Y OK Modify at Runtime 2 2 1,2 2 2 1,2 2 2

The PANEL control does not generate any events, therefore no update to the server will occur.

PROMPT
Attribute AT CENTER COLOR CURSOR DISABLE FONT FULL HIDE LEFT Supported Y Y Y Y Y Y Y Y Y OK Modify at Runtime 2 2 2 N 1,2 2 2 1,2 2

79

Controls Property Support

2 2 1,2 2

RIGHT SCROLL TEXT TRN

Y Y Y Y

The PROMPT control does not generate any events, therefore no update to the server will occur.

PROGRESS
Attribute AT COLOR CURSOR DISABLE FULL HIDE RANGE SCROLL TRN Supported Y Y Y Y Y Y Y Y Y OK Modify at Runtime 2 2 N 1,2 2 1,2 2 2 2

When a PROGRESS control is placed on a window the client window behaves slightly differently. Normally the client software does not contact the server unless the user has performed some activity to generate an EVENT. With a PROGRESS control present the client window periodically checks with the server to refresh the client window. The time between automatic refresh is set on the client side with the ProgressUpdateFrequency class property. When the client frequency is reached, a message is sent to the server to scan the current window and send the changes to the client. The change can consist of anything including the detection that another window has opened. The limitation to this is that the ACCEPT loop on the server must be cycling. This is essential because the message sent from the client will only be heard by the server when the ACCEPT loop gets an event. *

Note: Automatic client update requests will only occur when the

PROGRESS control is enabled. If disabled, the automatic update requests will stop.

RADIO
Attribute OK Modify at Runtime Supported

80

Controls Property Support

ALRT*** AT COLOR CURSOR DISABLE FLAT FONT FULL HIDE HLP ICON KEY LEFT MSG RIGHT SCROLL SKIP TEXT TOOLTIP TRN VALUE Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y N 2 2 N 1,2 2 2 2 1 1,2 2 2 N 2 2 2 2 2 2 2 2

***First 75 Alert Keys returned by {PROP:Alrt, x} except MouseLeft. The RADIO button will only send an EVENT to the server when an EVENT:AlertKey is generated. The only action on the client is to set the KEYCODE that causes the alert and post the EVENT:AlertKey to the server.

REGION
Attribute AT BEVEL COLOR CURSOR DISABLE DRAGID DROPID FILL FILLCOLOR FULL HIDE IMM SCROLL SELECTEDCOLOR TOOLTIP TRN Supported Y Y Y Y Y N N Y Y Y Y Y Y Y Y Y OK Modify at Runtime 2 2 2 N 1,2 N N 2 2 2 1,2 N N 2 2 2

81

Controls Property Support

If the mouse is clicked in the REGION, EVENT:Accepted is sent to the server. If the IMM attribute has been set, EVENT:MouseIn and EVENT:MouseOut is sent then the mouse enters and leaves the region. *

Note : Use IMM sparingly to keep network traffic low.

SHEET
Attribute ABOVE AT BELOW BROKENTABS COLOR CURSOR DISABLE DOWN FONT FULL HIDE HLP HSCROLL IMM JOIN KEY LEFT MSG NOSHEET RIGHT SCROLL SPREAD UP WIZARD Supported Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y OK Modify at Runtime N 2 N Y 2 N 1,2 Y 2 N 1,2 2 2 N Y 2 N 2 Y N 2 Y Y Y

The SHEET control generates the following events which trigger update information to the server: EVENT:AlertKey EVENT:NewSelection EVENT:Selected (when client property EventSelectedAllowed is set to 1) When a new tab is selected on the client, the SHEET control gets the event. The new tab CHOICE is sent to the server along with EVENT and KEYCODE. PROP:Selected is used to select the new tab on the server. The client program will receive the EVENT and can check which tab is displayed by using CHOICE. *

Note: EVENT:TabChanging is not sent.

82

Controls Property Support

SPIN
Attribute ALRT AT CAP CENTER COLOR CURSOR DECIMAL DISABLE FONT FULL HIDE HLP HSCROLL IMM INS INTOOLBAR KEY LEFT MASK MSG OVR RANGE REQ READONLY RIGHT SKIP SCROLL STEP TEXT (picture) TOOLTIP TRN UPR VSCROLL Supported Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y N Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y OK Modify at Runtime N 2 2 2 2 N 2 1,2 2 N 1,2 2 N 2 N N 2 2 N 2 N 2 N 2 2 2 N 2 2 2 2 N N

The SPIN control generates the following events which trigger update information to the server: EVENT:Accepted (and CONTENTS have not changed) EVENT:AlertKey EVENT:Selected, (client property EventSelectedAllowed is set to 1) EVENT:NewSelection (only if IMM is set)

83

Controls Property Support

After one of these events, the CONTENTS of the control, EVENT, and KEYCODE are sent to the Server.

STRING
Attribute ANGLE AT CENTER COLOR CURSOR DECIMAL DISABLE FONT FULL HIDE LEFT RIGHT TEST (picture) TRN Supported Y Y Y Y Y Y Y Y Y Y Y Y Y Y OK Modify at Runtime 2 2 2 2 N 2 1,2 2 2 1,2 2 2 2 2

The STRING control does not generate any events, therefore no update to the server will occur.

TAB
Attribute COLOR DISABLE FONT HIDE HLP KEY MSG TEXT (picture) TOOLTIP Supported Y Y Y Y Y Y Y Y Y OK Modify at Runtime 2 1,2 2 1,2 2 2 2 2 2

All activity for The TAB control occurs through its parent SHEET control. *

Note: The tab order cannot be changed at runtime.

TEXT
Attribute Supported OK Modify at Runtime

84

Controls Property Support ALRT AT CENTER COLOR CURSOR DISABLE FONT FULL HIDE HLP HSCROLL INS KEY LEFT MSG OVR READONLY REQ RIGHT SCROLL SINGLE SKIP TOOLTIP TRN UPR VSCROLL Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y N 2 2 2 N 1,2 2 2 1,2 2 N 2 N 2 2 2 2 N 2 2 2 2 2 2 2 2

TEXT controls can hold up to 65,000 characters in ClarioNET. The TEXT control generates the following events which trigger update information to the server: EVENT:Accepted (if the contents of the TEXT control have changed) EVENT:AlertKey EVENT:Selected, (client property EventSelectedAllowed is set to 1) After one of these events the CONTENTS of the control, the EVENT, and KEYCODE are sent to the server.

85

General Property and Control Notes

General Property and Control Notes

ClarioNET detects the attributes of all standard Clarion controls on each window. These properties are used to create the exact window replica that the client uses. Because the remote client screen is not truly attached to the server but simply a replica, not all properties can be supported. Nearly all control attributes (properties) are scanned and used when first building the control on the client. Thereafter, for each window update cycle, a subset of those properties is transmitted to the client. Use ClarioNET:SetUpdateExtents configure the settings for optimization of scanning for changed properties on a control. The property scanning in ClarioNET is very fast and efficient, being one of the most highly optimized areas of the code. Only consider limiting control scanning when you have actually assembled and used a ClarioNET web application and test both scan and non-scan alternatives.

Optimizing Scanning for Control Changes

ClarioNET:SetUpdateExtents(SHORT ControlType, SHORT Extent) ControlType : An integer constant, expression, EQUATE or variable that specifies the type of control to limit. EQUATE statements for the ControlType can be found in the EQUATES.CLW file. These equates are denoted by a prefix of CREATE:. A special CREATE:AddDelete ControlType is also available. Extent : An integer constant, expression, EQUATE or variable that defines the degree to which each controls properties are scanned. A value of zero (0) means that no scanning is done. A value of one (1) means that only the most basic properties are scanned for changes. This includes CONTENTS, HIDE, and DISABLE. A value of two (2) means that all control properties are scanned. This procedure sets the extent that ClarioNET investigates the server programs current CONTROL attributes for changes. Although ClarioNET is extremely fast in its window and control property scanning, windows with 500 to 1,500 controls can take a perceptible amount of time. There is also a special ControlType CREATE:AddDelete that is defined for ClarioNET. This specifies that the window is scanned for added or deleted controls at runtime and can take perceptible time for windows with over 400 controls. When the ControlType is set to CREATE:AddDelete the Extent parameter can be set to zero (0) to disable the check for added and deleted controls. If set to one (1) the checking for added and deleted controls is enabled. The default extent value for all controls (except CREATE:AddDelete) is two (2) and for CREATE:AddDelete it is one (1).

86

General Property and Control

CREATEing and DESTROYing Controls at Runtime

ClarioNET also scans your WINDOWs for new or missing controls at runtime. ClarioNET maintains a separate internal description of your entire window, and if a control is found (actually a Field Equate Label) that is not in the list it knows that the control has been created and then creates it on the client. The same thing occurs for deleted controls; if a control is found missing in the window it is deleted on the client.

The REQ Attribute : Required Fields

Controls with the REQ attribute, indicating it is a required field, are handled on the Client side in ClarioNET. Recall that the Clarion language specifies when a button with the REQ attribute is pressed, all ENTRY and TEXT controls with the REQ attribute are checked that they are not blank or zero. The first control encountered that does not contain data immediately receives input focus. In ClarioNET, when a client side button with a REQ attribute is pressed, the INCOMPLETE() procedure is called and the first blank or zero ENTRY or TEXT control receives focus.

MOUSEX() and MOUSEY()

Each time a client event and data are sent to the server the current CLIENT MOUSEX() and MOUSEY() LONG values are also sent to the server. HOWEVER a call to the servers MOUSEX() and MOUSEY() functions will not give you these values. Check the ClarioNETWindow.MouseX and ClarioNETWindow.MouseX class properties to get the latest mouse position on the client. *

Note : Because there might be screen scaling differences between server and client screens these values might not be totally reliable. This is because your server program, although not visible, has a virtual window associated with it that is scaled in dialog units according to your servers display settings and the basic font your WINDOW or APPLICATION has specified. The client might be running at a higher or lower resolution with large, small, or another size screen font.

Note! A common problem caused by a missing USE attribute is when controls are not visible on the client. If you notice missing controls or menu items, look first for a missing USE attribute in your server side program.

87

Redirected STD: function calls

Redirected STD: function calls

ClarioNET does not support Clarions STD syntax except for STD:Close, STD:PrinterDialog and STD:Help. STD:Close This STD attribute is supported. When this attribute is found on a control that received an event the client window is closed and POST(EVENT:CloseWindow) is posted to the server window. STD:Help, STD:HelpIndex, STD:HelponHelp, STD:HelpSearch These four STD:Help items are passed through to the client program. When you have specified a help file with the HELP Clarion procedure call and ClarioNET:EnableHelp has been used to turn help usage on, these STD: items will operate on the client. STD:PrintSetup This STD attribute is supported. When this attribute is found on a control that received an event, instructions are sent to the Client to display a PRINTERDIALOG window. When the -Client user finishes their selections the following client printer properties are set. for the current server system printer variable. PRINTER {PROPPRINT:Device} PRINTER {PROPPRINT:Paper} PRINTER {PROPPRINT:Paperheight} PRINTER {PROPPRINT:PaperWidth} PRINTER {PROPPRINT:Percent} PRINTER {PROPPRINT:Resolution} However there is no guarantee that these changes will effect the current server printer device that is being used by the server based program. The following STD attributes are not supported, and will display a Functionality Not Supported message window on the client, and will be ignored by the server program. STD:WindowList STD:CascadeWindow STD:Cut STD:Paste STD:Undo STD:TileVertical STD:TileWindow STD:ArrangeIcons STD:Copy STD:Clear STD:TileHorizontal

88

Redirected Clarion Standard

Redirected Clarion Standard Procedures

The changes to the BUILTINS.CLW file added OMIT/COMPILE statements that redirect many standard Clarion procedure calls to internal ClarioNET procedures. These ClarioNET procedures automatically detect when the program is running locally or has been launched by the Clarion Application Broker. The following standard Clarion procedures are redirected: POPUP BOX ELLIPSE ROUNDBOX SELECT GETINI DESTROY HIDE ARC LINE PIE SHOW ALERT HELP FIELD UNHIDE BLANK CHORD POLYGON TYPE PUTINI ASK IMAGE

89

Redirected Standard Dialog Boxes

Redirected Standard Dialog Boxes

ClarioNET redirects the standard your usage of the following Clarion functionality using the Clarion SYSTEM{PROP:?????Hook} capability. AssertHook ColorDialogHook FileDialogHook FontDialogHook

90

Run-Time Property Handling

Run-Time Property Handling

There are many runtime properties that the server program can read and write and provide additional Clarion functionality. PROP:AlwaysDrop Inspected on LIST and COMBO controls when first building the window for transfer to client. PROP:DeferMove & PROP:LazyDisplay Ignored. The client side of ClarioNET is the only displayed user interface; ClarioNET client side code handles all moves and refreshes for maximum speed. SYSTEM{PROP:ColorDialogHook} SYSTEM{PROP:FontDialogHook} SYSTEM{PROP:PrinterDialogHook} These properties are redirected to internal ClarioNET procedures that replicate the call on the client. Your server program receives a response identical to the program running locally. SYSTEM{PROP:FileDialogHook} Will display a message on the client that FILEDIALOG is not currently available in ClarioNET. PROP:HaltHook, PROP:StopHook, & PROP:AssertHook These properties are set to display a message box on the client and return the response to the server program. PROP:MaxHeight, PROP:MaxWidth PROP:MinHeight, PROP:MinWidth These properties are examined and sent to the client when first building a window. PROP:NoTips This property is checked both when first building the client window and for each update process. PROP:AcceptAll & SELECT() This deals with AcceptAll mode. ClarioNET is constantly checking SYSTEM{PROP:AcceptAll} from within the ClarioNET:TakeEvent procedure. When SYSTEM{PROP:AcceptAll} = 1 the call returns immediately.

91

Run-Time Property Handling

When AcceptAll finishes, either after finding a problem control or all controls are processed, SYSTEM{PROP:AcceptAll} is set to 0 by Clarion and the ClarioNET:TakeEvent processing continues. PROP:Checked Not used because examining the CONTENTS() of a CHECK control is more accurate. PROP:ChoiceFEQ Can be examined on the server program for current choice. Setting this property will have an effect only when ClarioNET tries to detect the {PROP:Selected} item in a SHEET or OPTION control. PROP:Edit Not available. PROP:EventsWaiting Used extensively within ClarioNET:TakeEvent to determine when all server program business logic. processing is finished and the screen can be scanned for transmission. PROP:Follows This property assigns a new tab order location for a control. Unfortunately there is no way that we can support tab order changes with the standard Clarion syntax. We have provided the procedure: ClarioNET:SetPropFollows(SIGNED ControlFEQ, SIGNED FollowsFEQ) ControlFEQ : The Field Equate Label of the control to change tab order. FollowsFEQ : The Field Equate Label of the control that should come immediately before ControlFEQ. This enables you to change the tab order at runtime. *

Note! If you CREATE a control at runtime always use this procedure call to set the tab order location of your newly created control.

PROP:HscrollPos &PROP:VscrollPos If you assign a value to these properties the ClarioNET Window update process will detect the change for the specific control and the client scroll position will be updated.

92

Run-Time Property Handling

PROP:IconList Fully supported in LIST controls. PROP:PrintMode ClarioNET sets this property in REPORT procedures to make sure that images on reports are written to the Clarion created WMF file. PROP:LineHeight This property is inspected when updating LIST and COMBO controls. PROP:Threading ClarioNET forces your server application to use the single document interface immediately within the call to ClarioNETServer:Init. This is accomplished by setting SYSTEM{PROP:Threading} = 0. This is an operational requirement of the Clarion Application Broker. PROP:Touched When an ENTRY, TEXT, SPIN, or COMBO has data modified by client action, PROP:Touched for that control is set to .1.. PROP:LineHeight This property is inspected when updating LIST and COMBO controls.

Forced Shutdown
A well behaved remote client automatically shuts down when no activity is apparent. When a specified time has elapsed and not activity has been performed on the client, both client and server programs will shut down automatically. In all cases the Clarion HALT procedure call is used to make sure that the executing program is completely shut down and all memory is deallocated. There are several scenarios that are considered. User stops using client program but does not exit In this case the Client No Activity Shutdown is examined. ClarioNET uses an internal timer to check if the user has performed an action within this period of time. If not it is assumed that the user has abandoned the session. The client sends the server a message to shut down, and the client then HALTs. To insure that the server program is stopped and completely removed from memory, a Clarion HALT is issued on the server also.

93

Run-Time Property Handling

Communication between client and server has been severed In this case the client and server portions have lost touch with each other. Similar to the client, the ClarioNET server extension has an internal timer that is always checking if it has heard from the client within the Server No Activity Shutdown time. If this time is exceeded then it is assumed that contact with the client is lost and a HALT is issued. When Continuous Connection is being used, the client is automatically contacting the server at certain intervals to let it know that it is still alive and waiting for user actions. There is no client inactivity time and the client and server can be considered a continuously running program. Both will continue operating until the connection between client and server is lost and the Server No Activity Time is exceeded, at which time the server program will issue a HALT.

94

Notes for Hand Coders

Notes for Hand Coders

Here is a general map of the critical procedure calls that control the system: !ClarioNETServer Initialization (Note 1) PROCEDURE !ClarioNET Window Initialization (Note 2) ACCEPT !ClarioNET Event Detection, Window Scanning & Client Notification ( Note 3 ) ! . . . . . . Code . . . . . . ! ClarioNET Window Close Signaling ( Note 4 ) END ClarioNET Window Kill ( Note 5 ) ClarioNET Server Close Down ( Note 6 ) This is a general overview of the cycle of interaction between ClarioNET and your server program. Numbers in parentheses refer to the map of critical procedures. (1) & (6) ClarioNETServer Initialization and CloseDown are accomplished with the calls to ClarioNETServer:Init and ClarioNETServer:Kill. These procedures initialize data structures and communicate with the Clarion Application Broker to gather the necessary server communication information. (2) ClarioNET Window Initialization must occur for each Clarion PROCEDURE that will display and process a Window. This is handled with the ClarioNET:OpenWindowInit, ClarioNET:InitWindow and ClarioNET:OpenWindow procedures. These procedures use a locally instantiated ClarioNETWindowClass class as a parameter used for keeping track of the Window and its current state. (3) Event Detection, Window Scanning, & Client Notification is the most important function call in the system. ClarioNET:TakeEvent must be the first call after ACCEPT so that it can monitor the status of the window. ClarioNET:TakeEvent has two purposes: (a) It detects when there are no more events waiting (PROP:EventsWaiting} = 0) so that the window can be scanned and sent to the client. (b) When a command is received from the client (EVENT:Request) the ACCEPT is triggered and ClarioNET:TakeEvent handles the incoming command.

During the server program operation, the ACCEPT loop is just looping through waiting for a TCP/IP-HTTP signal from the Client. When received, the Event and/or Data is posted to the proper window or control and the ACCEPT loop

95

Notes for Hand Coders

continues to process your code that senses the event and data change. Your Clarion server program has no idea where the change came from just that the event and data has changed. At this stage the Client is waiting for a response. The client is effectively dead until the server sends a response. The Clarion program continues to execute program code to finish the predetermined outcome of the event and/or data change. only when there are no events waiting in the ACCEPT loop does the ClarioNET:TakeEvent procedure again detect that {PROP:EventsWaiting} = 0 and scan the window, sending any changes to the client. (4) Window Close Signaling : It is critical that the client be informed when a Window is closing. This is the primary cause of the client going dead. Do not rely on .BREAK. to exit the ACCEPT loop. Always use POST(EVENT:CloseWindow). (5) ClarioNET Window Kill: When processing of a window is complete and the PROCEDURE is exiting, it is essential to call ClarioNET:KillWindow to DISPOSE of CLASSes instantiated for that Window and to notify the Client that the window is being closed. This is essential because the Client also must DISPOSE of CLASSes, exit a PROCEDURE, and then recontact the server to refresh the prior Window. (6) ClarioNETServer Close Down : When the program itself is terminating, ClarioNETServer:Kill must be called to cleanup and safely return all memory and resources to the server.

Note: The ClarioNET server extension is a one-pass system. Once your server program is launched and you call your first window, all further WINDOWs must be called from the top level WINDOW. After the first window is closed you can ONLY call the following server side ClarioNET procedures to contact the client:
ClarioNET:CallClientProcedure Any INI functions MESSAGE ClarioNET:ClientBeep ASK

ClarioNET Window Procedure Call Locations

There are six (6) procedure calls that must be placed in specific locations in any procedure that manages a window. These procedures form a unified system of keeping track of the window from startup to closedown. Do not consider these procedures something you can use to get alternative functionality. They have been designed as a unified set and should be left to do their work.

96

Notes for Hand Coders Sample PROCEDURE This declares the CLASS where ClarioNET stores all information for the window to be used. We recommend the definition is within the procedure data section

ClarioNETWindow ClarioNETWindowClass ! ! ! ! ! Window WINDOW('Caption'),AT(,,395,224) END

OPEN(Window) ClarioNET:OpenWindowInit(ClarioNETWindow) ! Records some EVENT information. ! MUST be before ! ClarioNET:InitWindow and ! AFTER OPEN(Window) ClarioNET:InitWindow(ClarioNETWindow, Window, 1) ! This is the main initialization ! function and MUST be called ! AFTER the window has been ! OPENed. Data structures are ! allocated, timers are examined, ! and other tasks to prepare for ! processing of the window. ACCEPT IF ClarioNET:TakeEvent(ClarioNETWindow) POST(EVENT:CloseWindow) ! This is the main processing END ! function. It MUST be the first ! executable code statement ! after ACCEPT. CASE EVENT() OF EVENT:CloseWindow ClarioNET:CloseWindow(ClarioNETWindow) OF EVENT:OpenWindow ClarioNET:OpenWindowInit(ClarioNETWindow) END ! ALWAYS exit the ACCEPT loop by posting EVENT:CloseWindow. !!!! END CLOSE(Window) ClarioNET:KillWindow(ClarioNETWindow) ! This procedure cleans up memory ! allocated inClarioNET:InitWindow ! and sends any required ! messages ! to the client to close its window.

97

Problems and Limitations

Problems and Limitations

ClarioNET has been heavily tested to make sure your deployment as easy and as powerful as possible. With just six procedure calls and one class instance per procedure there is hardly any code added to your application. But with this simplicity comes some limitations and potentials for coding mistakes which may break the client server communication alignment. Client does not launch program

No internet connection on the client computer. IP address or domain name specified by client is wrong Program name or directory structure are wrong specified in client program are wrong. The Clarion "EXE" Application Broker isnot running. Server program has attempted to start but DLL problems or file opening problems prevent it from opening. In this case display the program on the server to view possible windows that will reveal the problem. Server proram has attempted to start but no ClarioNET procedure calls have been placed into the program and the ClarioNET system is not called. Server program has attempted to start but when files are being accessed an error has occurred. Client launches program but during usage it freezes

You have not added the template to ALL your applications EXE and DLL APP files. The particular area of code being executed is using Edit-In-Place or Query by Example (QBE) functionality. A procedure has been called on EVENT:Timer. ClarioNET procedure calls have been placed by hand coding and either the locations or usage is incorrect. Problems in custom or third party code

If code writes directly to the screen using API calls these items will not appear on client.

98

Problems and Limitations

When using classes that override default ABC classes, there is a small chance that ClarioNET calls will not be added, or added in the wrong locations. Code or DLLs (custom or 3rd party) that are compiled without the BUILTINS.CLW file that we provide that controls the redirection of standard Clarion procedure calls can cause unstable behavior. Code or DLLs (custom or 3rd party) that are compiled without the ClarioNET procedure calls will hang the system when any of these windows are opened. ClarioNET Server Side Procedures Calls MUST be in specific locations The six procedure calls are designed to analyze your running application from various points of execution. Their location is critical. These procedures are: ClarioNET:OpenWindowInit ClarioNET:InitWindow ClarioNET:OpenWindow ClarioNET:TakeEvent ClarioNET:CloseWindow ClarioNET:KillWindow Calling Procedures That Display Windows in EVENT:Timer Do not call a procedure that requires user interaction to close from an EVENT:Timer. Window procedures can and must only be called in response to a user event. Because the server program is always waiting for client instructions, the client can only know whats happening in response to an event it sends to the server. Each ACCEPT loop that processes a window is designed so that it is waiting for a specific EVENT from the client program. An instruction can be sent to the client only after the client has contacted the server, and the client is waiting for a response. If you call a procedure on an EVENT:Timer, not only will the data stream that is sent to the client be ignored, but the server client alignment will be invalidated and both sides will be hung. This restriction does not apply to windows that will close themselves, as in small status windows with progress controls or text that changes as the event loop is cycled. Window Size is Incorrect on Client When you use INI files to save and restore WINDOW and APPLICATION size that subsequent runs may result in improper window sizes. This is because the Clarion size saving INI process reads the displayed windows size and saves it. There is a good chance that the window size on the server might be different than the client. You can of course change the size and location of the window and

99 Problems and Limitations

controls using runtime property assignments and the ClarioNET server code will transmit these changes to the client. We recommend that you disable the INI window size saving procedure upon testing ClarioNET:Active() = 1. A Call to POPUP Can Hang the Server This happens if... Modifications required to the BUILTINS.CLW file as described earlier were not performed You did not add ClarionetUsed as a project define. The POPUP menu will actually be processed on the server and the server program will be waiting for an answer.....an answer it cannot get. Window Controls on the Client are in the Wrong Order or MISSING When the client window is created a complex parent/child scanning operation takes place that creates parents before children, then creates controls in the proper tab order. It is essential that all controls have USE variables. Be especially vigilant of TABs and MENUs. Report Progress Windows that Require an EVENT to start printing A single guideline will make your report generation procedures work perfectly: do not combine a WINDOW with a REPORT procedure that requires user action. Perform all user selection processes to gather data that will be used to generate the report in a separate procedure. Let the REPORT procedure do just that...generate the report. Windows with PROGRESS Controls If a WINDOW or APPLICATION contains a PROGRESS control, the ClarioNET client will respond in a special way. After displaying the window the client will request a refresh of the window information at regular intervals. This behavior can be canceled by DISABLEing the progress control. Printout Size Limites or Orientation With ClarioNET, Clarions Report Print Preview mode must always be used.This is needed to force reports to print to Windows Metafiles) by the server program. The .WMF files are sent to the client. All metafiles for a single report are combined in a single compressed archive for transfer to the client. The maximum size is limited only to the practical transmission time to the client. WMF files compress to an average of 2 to 15K per page. ClarioNET has NO LIMITS to the complexity of a report page or the number of pages. There is only a common sense limitation that you need to determine

100

Problems and Limitations

because of the time it takes to send the compressed file of printout pages to the client. Be aware when a huge printout (2,000 + pages) could be generated that could take a long time to download to the client. Missing ICON or IMAGE contents Remember to place all images in the execute or public directory. Do Not use EVENT:Last in the Server program ClarioNET uses this EVENT as a trigger. Data within LIST is not formatted correctly or columns are shifted There is a maximum of 40 LIST and COMBO controls per window and a maximum of 200 QUEUE fields per LIST. If the listbox exceeds these limits your listbox data will not be formatted properly. Most often you will see records shifted over a number of columns as the list lines progress downwards. Also the vertical bar " | " character CAN NOT exist in the data records of the QUEUE. Whe ClarioNET uses special Clarion internal procedures to get the contents of a LIST Clarion uses a vertical bar to delimit the records. Wrong BUTTON has Default Behavior It is possible that you have used the DEFAULT attribute on a BUTTON control in a window more than once. ClarioNET recognizes this feature on the first BUTTON with the DEFAULT attribute as it scans the window in control specification order. Calling other Window procedures during Window startup Many times you may wish to call a splash type window during the opening process of a window. This is fine in ClarioNET but we recommend that you call the procedure to display the splash window BEFORE the ACCEPT loop begins or in the EVENT:OpenWindow location within the ACCEPT loop. If the splash window procedure that you have called returns a result that should cause the calling procedure to immediately RETURN, you can use a RETURN statement. Program "Lockup" Because ClarioNET maintains a strict client server alignment of events and window layering, it is essential that the two never lose their alignment. If alignment is lost there is no way to recover, and the link is considered dead. The server program will time out and terminate itself. The client program will exit after a time out, either from inactivity or because of an HTTP timeout event. This is the most common area of problems with ClarioNET and usually stems from a coding error in the server program.

101

Problems and Limitations

Font Sizes on the Client Because the client computer may be using a different screen resolution and screen font size than the server, there is the possibility the size of screen controls such as strings may be wrong. This is unavoidable and can be eased if you test your application in several screen resolutions to be sure everything fits well. When ClarioNET receives an APPLICATION or WINDOW to display it determines the basic font size that was used on the server and creates a window with the same size font. The resulting window should be nearly identical. MDI Apps become SDI Apps ClarioNET forces your application to run as a Single Document Interface application. This is required by the Clarion Application Broker. Please note the following items as you inspect your MDI application coding: POSTing events to other threads will have no effect. The event will be posted to the current thread. Please examine what could happened in the current ACCEPT loop received a POSTED event. Variables with the THREAD attribute become more global in scope. *

Note! There is no need to remove the START or MDI items from your program. START will simply become a procedure call and MDI will be ignored.

LIST Has Scrambled Entries This can be caused is there is a vertical bar "|" in the contents of one of the queue fields. Clarion internally uses this character as a delimiter when it is providing ClarioNET with the LIST contents. There is no way for us to change this at present, and we suggest that you filter this character out and change it to an alternative. API Calls That Write to Server Screen These will not appear on the clients screen. Third Party Code or DLL's If compiled without the revised BUILTINS.CLW these may hang the system if calling anything that was revised.

102

Additional Programming

Additional Programming Guidelines

For best display always specify X, Y, Width and Height for controls. If an AT parameter is left blank the field, as internally set by the Clarion runtime, might now be big enough to display the entire control.

103

Error Messages

Error Messages
These error messages will appear in a standard Clarion MESSAGE box if an error occurs. Client Error: Transfer File to Server Error Opening File: (filename) Error # (?) Error : ????? Skipping file The file specified on the client side to be transferred to the server could not be opened for the reasons stated in .Error.. Non-fatal error, the file will be skipped and not transferred. Client Error: Transfer File to Server Size of file : (filename) exceeds internal limits of (size) Skipping file The file was too large for the client side internal transfer buffers. Non-fatal error, the file will be skipped and not transferred. Client Error: Transfer File to Server Size of encoded file : (filename) exceeds internal buffer size of (size) Skipping file After the file was mime encoded and encrypted, the resulting datastream size was too large for the internal buffer. Non-fatal error, the file will be skipped and not transferred. Client: Shell Execute Error Error executing connection to : (command) This occurs when a button with ClarioNET:WEBLINK as the KEY equate was pressed and the ShellExecute command used ended in failure. Client: Non-Fatal Server Error Stream did not contain a header or receive encrypting Command = (datastream portion) A datastream has been received by the client that was not properly formatted by the server. This means that either the datastream was corrupted in transit via the TCP/IP connection or that some serious error has occurred on the server. Client: Datastream Error Unrecognized Assignment Function Code This indicates that one of the codes used on the server to tell the client what to do is not recognized by the client. If this happens the most likely problem is that the ClarioNET procedure calls in the server application are not properly placed -or- the basic logic used in the design of ClarioNET is being violated in the server program. The most common source of this message is when a new window is

104 Error Messages

opened when the client is expecting a simple update stream for the current window. Limit Exceeded Messages More than (x) variables required for screen. Number of Lists (x) exceeds internal limit of (x) queues Number of String USE variables exceeded All the above messages indicate that the screen was too large to be rendered on the Client. Your first action should be to reduce the number of controls on your screen. Also, contact ClarioNET, providing your window structures, so that the internal capacities might be increased in future editions. Client : Report Generation Error There was a data compression/encryption error... (info) when the report was being prepared for transmission. This indicates there was an error on the server when the files were being compressed and encrypted for transmission to the client. Client: File Error Client File Error on (filename) Location: (number) Error Value = (number) Error : (string) This is a general message when a file CREATE, OPEN, ADD, APPEND, CLOSE, or GET operation encountered an error. The .Location. number can be reported to ClarioNET to determine where the error occurred and aid in debugging for future problems. Client: Compression Error In-Ram Compression Initialization Error In-Ram Decompression Initialization Error This indicates that the main data compression/encoding system could not be initialized and is a fatal error. Please report this to ClarioNET. Client: Compression Error (1) Stream Compression Error Code: (number) (2) Stream Decompression Error Code: (number) This indicates an error has occurred during the compression/encryption process for sending data to the server. Please report this to ClarioNET. Client: Decompression Error Client Decompression System ERROR (string) This indicates that an error has occurred decompressing & decrypting the datastream received from the server. Please report this to ClarioNET. Server: Compression Error Server Compression System ERROR (text)

105

Error Messages
This indicates that an error has occurred compressing & encrypting a datastream to send to the client. Please report this to ClarioNET. Server: File Error Server File Error... Filename : (filename) Code Location Marker : (number) Calling Index : (number) Error # (number) Error : (text) This is a general message when a file CREATE, OPEN, ADD, APPEND, CLOSE, or GET operation encountered an error. The Location and Index values can be reported to the authors of ClarioNET to determine where the error occurred and aid in debugging for future problems.

106

107