Programming Manifold

Manifold may be programmed in several ways:

· "Ad hoc" programming using Active Columns in tables or ViewBots.

· Using SQL queries to alter table structure and otherwise make updates.

· Writing scripts using ActiveX scripting languages such as VBScript (the scripting edition of Visual Basic), JScript (also called JavaScript), Perl or Python, or .NET languages such as C#, VB .NET or JScript .NET. Scripts components may be created for Forms or may be created as standalone Script components.

· Scripts may invoke and control user interface elements such as dialogs.

· Calling Manifold System from external programs written in standard languages like Visual Basic and Visual C++ or their .NET equivalents.

· Adding scripts (which may call external COM objects) as custom toolbar buttons or menu items. See the Add-Ins topic for information on adding new toolbar buttons or menu commands.

· Programming in ASP or ASP.NET pages to create custom web pages that utilize Manifold IMS to create dynamic, Manifold-enabled web sites. Web applications on intranets are quite often the fastest, easiest and lowest cost way of creating customized GIS applications for distribution and use within an organization.

There is no additional programming language or toolkit that must be purchased in order to program Manifold. Every system includes the ability to use ActiveX languages or .NET languages to write sophisticated, forms-based programs using standard Windows controls. If you do have an external programming environment such as Visual Studio .NET, you can use that as well without the need to purchase any other options. You can even get a free Express version of Visual Studio from Microsoft.

Manifold also provides a Debugger for ActiveX scripting similar to those used in professional programming environments. The Debugger allows stepping through multiple scripts with automatic stops at breakpoints, paused execution and stepping into, over and out of routines. The Call Stack, Variables and Watches panes provide dynamic, editable displays of variables, functions, computed values and contexts. The Debugger works with VBScript, JScript and any other ActiveX scripting engine that supports Microsoft debugging calls. It is not used when scripting in a .NET language like C#.

Advice for Applications Developers

Many developers are creating commercial products based upon Manifold. There are two approaches, standalone applications or web applications, which in some sophisticated applications may be combined:

Standalone Applications

In this traditional way of creating and distributing applications a developer acquires however many Manifold licenses are required for the development team and an application is created that utilizes Manifold features through the API set forth in the Programming Reference chapter.

The application is then deployed using Manifold runtime licenses, which include the full Manifold API but not the Manifold GUI. A Manifold runtime license must be installed on every machine on which an application that calls Manifold facilities is deployed. That will require some means of keeping track of the serial number for each license and arranging for activation of each runtime license. Different developers have different preferences on how to arrange for installation and activation of the Manifold runtime license.

At one of the spectrum are developers who tell their customers to acquire, install and activate a Manifold runtime license before installing the developer's product. In this scenario the developer leaves it up to the customer to buy and to install and activate the necessary Manifold runtime. There are advantages and disadvantages to this strategty.

On the plus side, this stratety reduces the developer's use of cash to acquire and inventory Manifold runtime licenses and it eliminates the need for the developer to figure out how to acquire a Manifold license and then remotely install and activate it for the customer. However, on the minus side this strategy does risk that a potentially inexperienced customer might not license the right Manifold product or install and activate it correctly. It also makes it clearly known to the customer that Manifold is the engine used for the application. A final disadvantage is that if the developer does not copy protect the application then he or she will soon find out that a significant percentage of customers buy one application but then will acquire many Manifold runtime licenses to enable installation of that one application on many machines.

Many developers will charge much higher prices for their application than the price of a Manifold runtime license and so they will not want it advertised that their application is based upon Manifold. Such developers will prefer to handle all parts of the installation and will install the Manifold runtime as part of their application's installation. There are many different approaches to managing serial numbers and activating the runtime installation.

One approach favored by developers who send personnel to install applications and train customers is to have the developer's own personnel install and activate the runtime. A second approach favored by developers with applications that are intended to be installed by the customer is to use an automated approach to Manifold activation.

The usual automated approach is that the developer creates a small, web-hosted DBMS application that contains the serial numbers acquired by the developer for the Manifold runtime licenses acquired by the developer. When the developer sells an application he or she assigns the new customer a hash code that corresponds to an available license. The developer's application installation script includes a dialog in which the customer provides the hash code, allowing the installation script to connect to the developer's DBMS, grab the serial number associated with that hash code and then activate the Manifold runtime (using command line activation) with that serial number.

Either technique allows the developer to utilize Manifold's serial number and Activation key copy protection mechanism as a handy way of providing copy protection for their own applications as well (since the developed application won't run without an authorized Manifold runtime license). Developers are sometimes annoyed with the need to deal with Manifold activation until they realize how that mechanism discourages piracy of their own applications, at which point they become enthusiastic supporters of that Manifold mechanism.

See the Activation Keys and Serial Numbers topic for a discussion of the Manifold serial number and activation key mechanism. See the Developing Applications topic for specific advice of interest when developing standalone applications.

Web Applications

When customers are known to have an Internet connection available, many lightweight applications can be implemented as web applications that utilize Manifold IMS on a web server and free web browsers on client machines. In this case a developer will acquire Manifold licenses as needed for the development team and then deploy the application to a web server using either a runtime license or a regular license. Developers will often deploy to a web server using a full license because costs are so low in any case that they deem it worthwhile to have a fully interactive Manifold GUI available on the web server should it ever be necessary for debugging purposes.

There are many advantages to such an architecture, the most obvious being that there is near-zero cost for Manifold since client-side software consists of a free browser and the server-side software could consist of only a single Manifold runtime license. There are other advantages to web applications as well:

· Control over data - The applications developer can retain full control over data because it is resident on the server and need not be installed on client machines.

· Easier data updates - Changing data on the server instantly updates all client usage without need to distributed updated files to client machines.

· Easier application updates - Updating the application on the server updates the application for all clients.

· Potential for subscription model - A web based application allows business models that charge for application usage in real time. This allows conversion of what is usually a one-time purchase into a subscription or annuity, which can assist cash flow for developers.

· No redistribution issues - Because no vendor software is used client-side there is no need for the applications developer to deal with redistributing or activating runtime licenses into client machines.

Of course there are disadvantages to web applications as well. Web applications are limited by Internet bandwidth to lower performance applications than are possible with standalone applications. See the GIS and Networking and the What about Ajax? topics for a discussion of the issues involved.

Web applications can also require a greater amount of server-side programming in comparison to the local programming many programmers are familiar with using tools like the Microsoft Express series.

Advice for New Programmers

Because Microsoft languages and language standards are used within Manifold, to program Manifold we need to understand the Microsoft approach to languages and to Windows programming. In addition, although Manifold System is itself coded entirely in Microsoft Visual C++, many applications developers prefer to work with Microsoft's Visual Basic languages for customization of applications.

Experienced programmers already have strong opinions as to the languages they prefer. In modern times, most experienced programmers are already working with Visual Studio .NET using some .NET language they like. In contrast, beginners often start with scripts using some scripting language and, in the Microsoft world, often begin using some version of Visual Basic. It is therefore important to understand the differences between various versions of Visual Basic offered by Microsoft. This topic provides some guidance for beginners, to help them avoid traps such as coding in VBA.

Microsoft BASIC and Scripting Languages

At the present time, there are several Microsoft languages of interest to beginning Windows developers who do scripting or who prefer to work with a BASIC language:

Javascript (JScript or JScript .NET) - JScript is Microsoft's superb implementation of the widely used Javascript language, a scripting version of the Java language. Javascript is a favorite of "cross platform" writers creating Internet applications who wish to write scripts that work with many different browsers on Windows and non-Windows operating systems. JScript is an interpreted language that executes within an ActiveX scripting engine.

Visual Basic (VB or VB .NET) - A full-fledged development language that is normally used within Microsoft's Visual Studio development environment. Visual Basic is a compiled language. Many professional applications that are not coded in Visual C++ are coded in Visual Basic. Visual Basic includes superb editing, forms creation and other accessories that facilitate use of this language.

Visual Basic Scripting Edition (VBScript) - A subset of Visual Basic that is a very widely used scripting language, in part because it comes free with every copy of Microsoft's Internet Explorer browser and may be freely redistributed with applications created using Visual Studio. VBScript is the scripting language of choice (with JScript being a second choice) for Microsoft web applications. It is the main language used with ActiveX scripting. Microsoft's push into Internet has made VBScript immensely popular and well supported by third parties with numerous books and objects. An interpreted language, VBScript has become so popular that third parties (such as manifold.net) are now extending it with forms creation and other tools. VBScript is virtually identical to VB so expertise in either VB or VBScript is automatically useful in the other language as well. VBScript has also emerged as the main language used to configure and customize Microsoft's Enterprise class servers.

Visual Basic for Applications (VBA) - A VB variation that likely would have no life were it not bundled with Microsoft's own Office applications. This is a Visual Basic of sorts that is embedded within an application. It is an interpreted language, so any programs or add-ins written in it automatically deliver the source code for the add-in to every user (a real showstopper for most commercial developers). In recent years Microsoft has tried to sell VBA under license for use by third parties; however, despite a marketing push by Microsoft as of this writing fewer than 200 non-Microsoft applications use VBA. There are two main reasons VBA has not caught on: For professional applications, VBA has a high hassle-factor without offering the benefits of true Visual Basic or Visual Studio. For casual use VBA is not significantly better than VBScript while costing far more (potentially adding hundreds of dollars of end user cost) and being clumsier. At one point, VBA had a richer set of tools than VBScript but the surging popularity of VBScript has erased that advantage.

Even within Office application programming, VBA is being pushed aside by programming in real VB or the use of VBScript. As popular as VBA has been for amateur programmers in the Office application programming niche, the engineering team at manifold.net believe that VBA is a technological and business dead-end. We think that the highest value approach to programming with applications in Microsoft operating systems is a two-fold approach using VBScript and VB:

· Use Visual Basic Scripting or JScript for rapid scripting within Manifold. There is so much support for these languages as a result of the growth of Internet that they are clearly the way to go for casual scripting. By adding some elegant support facilities such as Manifold's form designer, they can be used to do everything VBA can do, but without the overhead, cost, hassle-factor and weirdness of VBA. Scripts written in VBScript or JScript are perfect for use within Active Columns as well. If possible, move to the .NET versions of these languages in order to take advantage of .NET capabilities.

· Use Visual Basic or Visual C++ within Visual Studio for extensive applications development with Manifold. This allows source code protection within compiled code, the speed advantages of compiled code and most importantly the ability to use the full array of professional code-warrior tools available within Studio. SourceSafe alone is worth the jump to Studio when working in teams and the Visual Studio editor is a dream come true.

· Of course, when coding in .NET environments (a good idea), use Visual Basic .NET or JScript .NET or C#, the .NET equivalents of the above two strategies. Although coding with .NET involves a steeper learning curve for the complete beginner, almost all professional programmers working in Microsoft environments are writing .NET code. If writing code is an important part of your professional life, the sooner you get a copy of Visual Studio .NET and get your head around .NET, the better.

The above, two-fold approach appears to be the strategy chosen by Microsoft itself for all of its next generation products. A review of Microsoft's online Knowledge Base and other resources on the www.microsoft.com site shows extensive Microsoft use of VBScript or Visual Studio tools for .NET and the Enterprise servers such as SQL Server, Commerce Server and Exchange Server, but virtually no new work in VBA outside of a handful of consumer examples for Office.

Users of Visual Studio need no encouragement for coding in this superb environment. For world-class, professional program development, get a copy of Visual Studio .NET and learn to code in .NET using Visual C++ or Visual Basic .NET. Microsoft makes it easy for people to get started by providing free downloads of the Express version of Visual Studio. Go for it!

To support the use of VBScript for casual scripting, manifold.net has developed forms-based, drag and drop tools drawn from our experience with Windows and Visual Studio that make it very easy to write scripts of amazing sophistication and power in VBScript. In fact, VBScript is so good and the Manifold development environment so easy to use, it is quite likely that professional developers as well as proficient amateurs might reach first for VBScript even for complex tasks.

Using VBScript also means that no additional software is required to program scripts of great sophistication in Manifold. There is no need to purchase Visual Basic or other Visual Studio components, no need to buy any third party accessories, no SDK, and no embedded license fee for VBA. If you have Manifold System you can program right away using true Windows, event-driven and forms-based programming methods. VBScript is a fine "first language" to learn for someone who has never programmed before. It's fast, easy, fun and when it is used with ActiveX controls it is extremely powerful for many practical purposes.

VBScript scripts in Manifold can call any standard ActiveX object if desired. For example, one can add a third party ActiveX control to a form that draws a custom picture of some sensing instrument's readout. There are many thousands of freeware, shareware and inexpensive ActiveX controls we can use in Manifold scripts. Manifold provides a large "starter set" of fun controls like calendars, toolbars and other useful items.

Although Manifold scripts may be written in VBScript or JScript (or even PERL or Python) all of the documentation examples and other support resources from Manifold are based on VBScript. Technically, any ActiveX scripting engine language that you have installed in your machine can be made to work. However, to keep documentation and tech support down to a realistically manageable size we focus on VBScript. There is no technical support available from manifold.net for scripting languages other than VBScript. If you choose to work in other languages it is up to you to learn enough about VBScript and Microsoft methods to figure out how to translate what is said in a VBScript context to your language.

This documentation also assumes the programmer is fluent in Windows programming. Windows programming is based on an event-driven model, which is very different than traditional, "procedural" applications programming. Although there are tips scattered throughout this documentation (including the brief introduction below), if you are not fluent in Windows programming you will need to get some good books on Visual Basic, VBScript, Windows, ActiveX and other key Microsoft products and concepts. There are hundreds of good choices. Because Manifold uses standard Microsoft languages and methods you have an entire world of resources to utilize.

One small caveat: because VBScript is so popular for web stuff scripting, many books will discuss it in the middle of lots of other talk about HTML, Active Server Pages (ASP) and other web topics. That's OK. The same characteristics that make VBScript a good first choice in web programming also make it ideal for casual scripting in Manifold as well. The only differences between VBScript books with a web orientation and VBScript use in Manifold will be the environment within which one actually writes the scripts.

Windows Programming

Almost everything we see in a Windows application is itself a window. That includes not only the usual "windows" in which applications such as Windows Explorer or Manifold run, but also all the various command buttons, toolbar buttons, dialogs, menu bars and other items one sees on screen. A "window" is just a rectangular region. Each window in Microsoft Windows is assigned a unique id number called the window handle or hWnd.

The operating system continuously surveys each window for any activity. Different types of activity, such as a mouse click or the window being uncovered by another window is an event. When the operating system sees an event occur, it sends a message to all windows, broadcasting news of the event to literally all of the windows. Each window then decides what to do with that message by consulting whatever instructions it has on hand for handling messages of that sort. For example, a window can repaint itself if it has been exposed by another window. Most messages are handled for us automatically by the Windows operating system so we rarely need to think about low-level housekeeping details. Higher level messages are exposed as event procedures that we can utilize as we see fit.

Event-Driven Programming

Traditional, "procedural" languages like the original BASIC language are conceptually quite simple: the program begins at the first line of code and then steps through all the other lines of code in order, making departures from time to time to visit procedural subroutines or to follow loops.

Event-driven programming is quite different, since any part of the code might be called at any time when an event that triggers it occurs. We have to write our code so that any assumptions we make we know will be true at all times. For example, we should keep an "OK" command button disabled if it requires user entry of text into an edit box until we know the edit box actually contains text. Since programs as well as humans can write text into a text box (and thus trigger an event), we have to keep in mind that things may change without human user intervention. This model requires some more thought but it is wonderfully flexible and often results in far more reusable and adaptable code than traditional procedural code.

Forms-Based Programming

Traditional languages involve development along a typical path consisting of three steps: writing the code, compiling it, and then running it. We iterate through this path over and over when creating an application. Creating the user interface in traditional applications is an interwoven part of writing the code and at times will result in spaghetti code connections between various parts of the program to service different user interface situations.

Because everything in Windows programming revolves around windows, events and messages, we take a different approach in most Windows programming and use Forms-Based programming. This involves three steps:

· Create the user interface (a form).

· Set properties for the controls used in the form.

· Write code within a script that implements program logic and tells the controls what to do.

Forms are used to create the windows used to interface to your script or application. They are also used to view tables and otherwise interact with databases through a forms-based human interface. In Manifold, we use the File - Create - Form menu command to create a new form. We can then pop open that form and add controls to it from the Tools toolbar, from the Tools (Advanced) toolbar or from other sources.

Next, we set the properties for each item in the form if we would like to change them from the defaults. This lets us take advantage of the very rich set of automated user interface capabilities Windows provides to control appearance and behavior and otherwise deal with events.

For example, instead of showing a command button as a simple 3D button with a caption we can show it as button with an image on it. We can even use different images in the up and down position, if desired. If we like, in about three seconds we can change the button's properties so that whenever the mouse cursor passes over it the cursor will change to a custom graphic. Cool!

Finally, we open the script associated with the form and write the code that powers the form in VBScript using classic ActiveX, Visual Basic and Windows ideas such as objects, object properties, and object methods. The discipline of having a form that keeps our controls and their properties well organized is a great help in keeping our code clearly organized.

The above sequence of three steps in forms-based programming is typical of Visual Basic application development within Visual Studio. The magic of Manifold System is that the above methodology also may be used with VBScript within Manifold scripts as well. This allows rapid development of sophisticated scripts that provide first-rate user interfaces created in a point-and-click manner.

ActiveX Languages

Scripting within Manifold is implemented using either .NET languages or ActiveX scripting. This means that you can use any language for scripting within Manifold for which an ActiveX scripting engine is installed on your computer. Always present are VBScript and JScript because these are installed with Internet Explorer, a required prerequisite for running Manifold.

At the present writing downloadable, free-of-charge ActiveX scripting engines for PERL and Python are available from sources such as www.activestate.com. End users may download these engines, install them and then merrily write Manifold scripts in either PERL or Python. manifold.net personnel have experimented enthusiastically with both languages on a casual basis.

Other scripting languages, such as REXX and Tcl/Tk, are said to be available as ActiveX scripting engines and presumably could be used within Manifold. These have not been used at manifold.net but we would be interested in hearing from users who have experimented with them or with any other scripting languages within Manifold.

The practical limitations of development and technical support mean that Manifold's form based programming facilities are designed for VBScript. Users of other languages should not expect to be able to use Manifold's forms and drag and drop controls with those languages. If you work with those other languages you should plan on scripting within the ordinary, text-based facilities of that language. Nonetheless scripts of immense power can be created using languages other than VBScript. We think it's neat that Manifold users can choose the scripting language they like best for the task at hand.

Choosing a Scripting Language

To specify a language other than VBScript, open a script for editing in a script window and then choose Script - Language . This dialog allows choice of which scripting language is used. Any scripting language installed in your Windows system may be used. Examples in this documentation are provided for VBScript, JScript, ActivePython, and ActivePERL (the latter two languages from www.activestate.com). Overall, we suggest use of VBScript, JScript, C#, JScript .NET or Visual Basic .NET.

Although .NET languages like C# can have a slightly steeper learning curve for total beginners than ActiveX scripting languages like VBScript or JScript, it is clear that more and more people, even beginners, are writing their Manifold scripts in .NET languages.

A Future for VBA Enthusiasts

Avid VBA users may rise to the defense of VBA and may complain this topic overstates the case against VBA. It's true that VBA is a beloved first introduction to VB for many people who are transitioning from casual macro creation and application configuration into serious, professional programming. For that, one should be grateful for VBA, but one's gratitude should not cloud one's eyes into not seeing the many disadvantages of VBA compared to real VB, VB .NET or VBScript.

If you have spent years working with VBA, be happy that you have invested time and effort into developing expertise that is readily portable into VB, VB .NET and VBScript. If you like VBA you'll love working in VB .NET in Visual Studio .NET and you'll feel right at home snapping out sparkling web stuff and Manifold scripts in VBScript.

.NET and Version Skew

Manifold utilizes Microsoft's .NET Framework which is being actively evolved for everyone's benefit by Microsoft. Developers should therefore take care to pay attention to what versions of the .NET Framework and their development tools are in use.

For example, Visual Studio .NET 2003 only supports .NET 1.1 assemblies, not .NET 2.0 assemblies. Manifold 6.50 used .NET 1.1 and so could be used with Visual Studio .NET 2003. In contrast, however, Manifold 6.50 SP1 uses .NET 2.0 and so requires Visual Studio .NET 2005 or later.

If we do not yet have Visual Studio .NET 2005, we can download various Express editions of it for free from the Microsoft web site.

Scripting the User Interface

Manifold scripts can control user interface elements such as dialogs. A script that controls the user interface must run in a separate thread, which can be arranged via the Properties context menu that pops up when we right click on a script in the project pane and choose Properties. This menu allows us to check the Run in separate thread property. Running a script in a separate thread allows using advanced scripting techniques such as scripting the user interface, but might be slightly slower in some cases. By default, the option is turned off. See the User Interface Scripting topic.

Notes

Visual Basic .NET is often abbreviated "VB .NET" within Manifold dialogs, apparently inserting an extra space between the "VB" and the ".NET." This usage follows the most common Microsoft practise. However, Microsoft is so large that there is not a totally uniform usage within the company and some Microsoft publications will use "VB .NET", "VB.Net" and even "VB NET." This documentation tends to use VB .NET.

Within Manifold, all .NET assemblies (including Manifold.Interop) are installed into the global assembly cache to facilitate reuse.

Internet Resources

Visit the Manifold website at http://www.manifold.net and drill down into the Free Stuff page for links to scripting and programming examples.

Visit the Support page on the Manifold website to find links to the latest Manifold User Group forums in which scripting and programming are discussed. It is extremely important to tap into the collective experience of the Manifold user community when first learning to program Manifold System. Seeing examples and reading discussion on programming is a very important part of learning.

The easiest forum to access is the Georeference forum originally started by the Manifold System User Group and now run by the Manifold online community. Click on the Forum page at the manifold.net home page or simply visit http://forum.manifold.net - Thousands of Manifold users from all over the world meet at that forum to discuss Manifold System, programming, IMS and related topics.